/ Hex Artifact Content
Login

Artifact 02352d9488394a3489b2d153360da58a7c392070:


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 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
23f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2400: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2410: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2420: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2430: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2440: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2450: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2460: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2470: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
2480: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
2490: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24a0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24b0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24d0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
24e0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
24f0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2500: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2510: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2520: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2530: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2540: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2550: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2560: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2570: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
2580: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
2590: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25b0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25d0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
25e0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
25f0: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2600: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2610: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2620: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2630: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2640: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2650: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2660: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2670: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2680: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2690: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26a0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26b0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26c0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26d0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
26e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
26f0: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2700: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2710: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2720: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2730: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2740: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2750: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2760: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2770: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
2780: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2790: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27a0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27b0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27d0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
27e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
27f0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2800: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2810: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2820: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2850: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2860: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2870: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2880: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2890: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28b0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28d0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
28e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
28f0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2900: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2910: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2920: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2930: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2940: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2950: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2960: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2970: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2980: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2990: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29a0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29b0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29d0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
29e0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
29f0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a00: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a50: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a60: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a70: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2a80: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2a90: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2aa0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2ab0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2ac0: 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75  associated resou
2ad0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2ae0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ated..**.** Appl
2af0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73  ications must [s
2b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
2b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b30: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
2b40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2b50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2b60: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
2b70: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b90: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ba0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2bb0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2bc0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2bd0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ose() is called 
2be0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
2c00: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
2c10: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
2c20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f  ed statements] o
2c30: 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  r [BLOB handles]
2c40: 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  , then it return
2c50: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  s.** SQLITE_BUSY
2c60: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c  ..**.** ^If [sql
2c70: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
2c80: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
2c90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ca0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
2cb0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
2cc0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2cd0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
2ce0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2cf0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2d00: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
2d10: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2d20: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
2d30: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
2d40: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
2d50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
2d60: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2d70: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
2d80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2d90: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2da0: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2db0: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
2dc0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68  te3_close() with
2dd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2de0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a  argument is a .*
2df0: 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  * harmless no-op
2e00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e10: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2e20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2e30: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2e40: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2e50: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2e60: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2e70: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
2e80: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
2e90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2ea0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2eb0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2ec0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2ed0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ee0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2ef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f00: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2f10: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2f20: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
2f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2f40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2f50: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
2f60: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
2f70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f80: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2f90: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2fa0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
2fb0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
2fc0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
2fd0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
2fe0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
2ff0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3000: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3010: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3020: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3030: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3040: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3050: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3060: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3070: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3080: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3090: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
30a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
30b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
30c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
30e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
30f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3100: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3110: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3120: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3130: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3140: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3150: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3160: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3170: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3180: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3190: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
31a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
31b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
31c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
31d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
31e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
31f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3200: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3210: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3220: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3230: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3240: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3250: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3260: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3270: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3280: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3290: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
32a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
32b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
32c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
32e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
32f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3300: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3310: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3320: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3330: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3340: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3350: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3360: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3370: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3380: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3390: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
33a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
33b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33c0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
33d0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
33e0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
33f0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3400: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3410: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3420: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3430: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3440: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3450: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3460: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3470: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
3480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3490: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
34a0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
34b0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
34c0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
34f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3500: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3510: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3520: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3530: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3540: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3550: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3560: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3570: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3580: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3590: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
35a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
35b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
35c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
35d0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
35e0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
35f0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3600: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3610: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3620: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3630: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3640: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3650: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3670: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3690: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
36a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
36c0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
36d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
36f0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3700: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3710: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3720: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3730: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3740: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3750: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3760: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3770: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3780: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3790: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
37a0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
37b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
37c0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
37d0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
37e0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
37f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3800: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3810: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3820: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3830: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3840: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3850: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3860: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3870: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3880: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3890: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
38b0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
38c0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
38d0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
38e0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
38f0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3900: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3910: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3920: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3930: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3940: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3950: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3960: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3970: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3980: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3990: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
39a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
39b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
39c0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
39d0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
39e0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
39f0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3a00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3a10: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3a20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3a30: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
3a40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a50: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3a60: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3a90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3aa0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ab0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3ac0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
3ad0: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
3ae0: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
3af0: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
3b00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3b10: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
3b20: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
3b30: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
3b40: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
3b50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3b60: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 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 20 20 2f                 /
3b90: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3ba0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3bb0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3be0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3bf0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3c00: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3c10: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3c20: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3c30: 2f 0a 20 20 76 6f 69 64 20 2a 2c 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 20 20 2f                 /
3c60: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3c70: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3c80: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **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 20 20 2f 2a 20 45 72             /* Er
3cb0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3cc0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3cd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3ce0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
3cf0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3d00: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3d10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
3d20: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
3d30: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
3d40: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3d50: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3d60: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3d70: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3d80: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3d90: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
3da0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
3db0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3dc0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3dd0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3de0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3df0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3e00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3e10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3e20: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3e30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3e50: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3e60: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3e70: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3e80: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3e90: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3ea0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3eb0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3ec0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3ed0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3ef0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3f00: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3f10: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f30: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3f40: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3f50: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3f60: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3f70: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3f80: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3f90: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3fa0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3fb0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3fc0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3fd0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3fe0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4000: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4010: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4020: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4040: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4050: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4060: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4070: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4080: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4090: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
40a0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
40b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40c0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
40d0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
40e0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
40f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4110: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4120: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4130: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4140: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4160: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4170: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4180: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4190: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
41a0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
41b0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
41c0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
41d0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
41e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41f0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4200: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4210: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4220: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
4230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4240: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4250: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4260: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4270: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4290: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
42a0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
42b0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
42c0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
42d0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
42e0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
42f0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4300: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4310: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4320: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4330: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4360: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4370: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4380: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4390: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
43a0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
43b0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
43c0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
43e0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
43f0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4400: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4410: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4420: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4430: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4440: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4460: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4470: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4480: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
44a0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
44b0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
44c0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
44d0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
44f0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4500: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4520: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
4530: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
4540: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4550: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4560: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4570: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4590: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
45a0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
45b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
45c0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
45d0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
45e0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
45f0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4610: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4620: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4630: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4640: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4650: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4660: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4670: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4680: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4690: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
46a0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
46b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
46c0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
46d0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
46e0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
46f0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4700: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4710: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4720: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4730: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4740: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4750: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4760: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4770: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4780: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4790: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
47a0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
47b0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
47c0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
47d0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
47e0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
47f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4800: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4810: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4820: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4830: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4840: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4850: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4860: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4870: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4880: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4890: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
48a0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
48b0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
48c0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
48d0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
48e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
48f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4900: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4910: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4920: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4930: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4940: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4950: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4960: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4970: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4980: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4990: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
49a0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
49b0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
49c0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
49d0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
49e0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
49f0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4a00: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4a10: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4a20: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4a30: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4a40: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4a50: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4a60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a70: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4a80: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4a90: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4aa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4ab0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4ac0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4ad0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4ae0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4af0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4b00: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4b10: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4b70: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4bf0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d60: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4d70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d80: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4da0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4db0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4dc0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4de0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4df0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e00: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e20: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e40: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e60: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4e70: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4e80: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ea0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ec0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f00: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f20: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f40: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f60: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
4f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f80: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
4f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fa0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
4fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fc0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
4fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fe0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
4ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5000: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5020: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5030: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5040: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5060: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5070: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5080: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
50a0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
50c0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
50e0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5100: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5120: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5140: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
51b0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
51c0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
51d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
51f0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5210: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
5220: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5230: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5240: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5250: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5260: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5270: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5280: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5290: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
52a0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
52b0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
52c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
52d0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
52e0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
52f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5300: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5310: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5320: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5330: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5350: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5360: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5370: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5380: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53a0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
53b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
53c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
53d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
53e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53f0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5400: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5410: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5430: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5440: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5450: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5470: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5480: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5490: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
54a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54b0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
54c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
54d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
54e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
54f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5500: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5510: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5520: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5540: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5550: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5560: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5580: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5590: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
55a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
55d0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
55e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5600: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5610: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5620: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5640: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5650: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5660: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5680: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5690: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
56a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
56b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56c0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
56d0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
56e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
56f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5720: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5730: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5740: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5760: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5770: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5780: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5790: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
57a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57b0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
57c0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
57d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
57e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5800: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5810: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
5820: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5830: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5860: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5870: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5880: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5890: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
58a0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
58b0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
58c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
58d0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
58e0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
58f0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
5900: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
5910: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5920: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5930: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5940: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5950: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5960: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5970: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5980: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5990: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
59a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
59b0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
59c0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
59d0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
59e0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
59f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5a00: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5a10: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5a20: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5a30: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5a40: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5a50: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5a60: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5a70: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5a80: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5a90: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5aa0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5ab0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
5ac0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
5ad0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
5ae0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
5af0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
5b00: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
5b10: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5b20: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5b30: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5b40: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5b50: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5b60: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5b70: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5b80: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5b90: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5ba0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5bb0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5bc0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5bd0: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
5be0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
5bf0: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
5c00: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
5c10: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
5c20: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
5c30: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
5c40: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
5c50: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
5c60: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
5c70: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
5c80: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
5c90: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
5ca0: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
5cb0: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
5cc0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
5cd0: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
5ce0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
5cf0: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64  unchanged..*/.#d
5d00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d10: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
5d20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d30: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
5d40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d50: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
5d60: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
5d70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5d80: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
5d90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5da0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
5db0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
5dc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5dd0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
5de0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5df0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
5e00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5e10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
5e30: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e40: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
5e50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5e60: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
5e70: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
5e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5e90: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
5ea0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5eb0: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
5ec0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5ed0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
5ee0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
5ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5f00: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
5f10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5f20: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
5f30: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5f40: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
5f50: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
5f60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5f70: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
5f80: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
5f90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5fa0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
5fb0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
5fc0: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
5fd0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
5fe0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
5ff0: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6000: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
6010: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6020: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6030: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
6040: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
6050: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6060: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6070: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6080: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6090: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
60a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
60b0: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
60c0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
60d0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
60e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
60f0: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6100: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6110: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6120: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6130: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6140: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6150: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6160: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6170: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6180: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6190: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
61a0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
61b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
61c0: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
61d0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
61e0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
61f0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6200: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6210: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6220: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6230: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6240: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6250: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6260: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6270: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6280: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6290: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
62a0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
62b0: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
62c0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
62d0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
62e0: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
62f0: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6300: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6310: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6320: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6330: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6340: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6350: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6360: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6370: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6380: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6390: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
63a0: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
63b0: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
63c0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
63d0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
63e0: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
63f0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6400: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
6410: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6420: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
6430: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
6440: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
6450: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
6460: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
6470: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
6480: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
6490: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
64a0: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
64b0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
64c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
64d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
64e0: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
64f0: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
6500: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
6510: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
6520: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
6530: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
6540: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
6550: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
6560: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
6570: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
6580: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
6590: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
65a0: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
65b0: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
65c0: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
65d0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
65e0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
65f0: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
6600: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
6610: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
6620: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
6630: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
6640: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
6650: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
6660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6670: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
6680: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
6690: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
66a0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
66b0: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
66c0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
66d0: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
66e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
66f0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
6700: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
6710: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
6720: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
6730: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
6740: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
6750: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
6760: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
6770: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
6780: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
6790: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
67a0: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
67b0: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
67c0: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
67d0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
67e0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
67f0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
6800: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
6810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
6820: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6830: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6840: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
6850: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
6860: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
6870: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
6880: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
6890: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
68a0: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
68b0: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
68c0: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
68d0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
68e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
68f0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
6900: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
6910: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
6920: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6930: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
6940: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
6950: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
6960: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
6970: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6980: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
6990: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
69a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
69b0: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
69c0: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
69d0: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
69e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
69f0: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
6a00: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
6a10: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
6a20: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
6a30: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
6a40: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
6a50: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
6a60: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
6a70: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
6a80: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
6a90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
6aa0: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
6ab0: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
6ac0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
6ad0: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
6ae0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
6af0: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
6b00: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
6b10: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
6b20: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6b30: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
6b40: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
6b50: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
6b60: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6b70: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
6b80: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
6b90: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
6ba0: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
6bb0: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
6bc0: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
6bd0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
6be0: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
6bf0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6c00: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
6c10: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6c20: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
6c30: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
6c40: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
6c50: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6c60: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6c70: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
6c80: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
6c90: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
6ca0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
6cb0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
6cc0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
6cd0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
6ce0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
6cf0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
6d00: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
6d10: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
6d20: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
6d30: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
6d40: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
6d50: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6d60: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6d70: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6d80: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6d90: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6da0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6db0: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
6dc0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6dd0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
6de0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6df0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
6e00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6e10: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
6e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6e30: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
6e40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
6e50: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6e60: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6e70: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6e80: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6e90: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6ea0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6eb0: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6ec0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6ed0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6ee0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6ef0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
6f00: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
6f10: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
6f20: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
6f30: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
6f40: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
6f50: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6f60: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6f70: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6f80: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6f90: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6fa0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6fb0: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6fc0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6fd0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6fe0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6ff0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7000: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
7010: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7020: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7030: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7040: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
7050: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
7060: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7070: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7080: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7090: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
70a0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
70b0: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
70c0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
70d0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
70e0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
70f0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7100: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7110: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7120: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7130: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7140: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7150: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7160: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7170: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7180: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7190: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
71a0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
71b0: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
71c0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
71d0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
71e0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
71f0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7200: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7210: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7220: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7230: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7240: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7250: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7260: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7270: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7280: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7290: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
72a0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
72b0: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
72c0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
72d0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
72e0: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
72f0: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7300: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7310: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7320: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7330: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7340: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7350: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7360: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7370: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7380: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7390: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
73a0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
73b0: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
73c0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
73d0: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
73e0: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
73f0: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7400: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7410: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7420: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7430: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7440: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7450: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7460: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7470: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7480: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7490: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
74a0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
74b0: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
74c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
74d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
74e0: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
74f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7500: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7510: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7520: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7530: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7540: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7550: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7560: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7570: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7580: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7590: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
75a0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
75b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
75c0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
75d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
75e0: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
75f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7600: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7610: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7620: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7630: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7640: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7650: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7660: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7670: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
7680: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7690: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
76a0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
76b0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
76c0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
76d0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
76e0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
76f0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
7700: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
7710: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
7720: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
7730: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
7740: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7750: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7760: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7770: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
7780: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7790: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
77a0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
77b0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
77c0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
77d0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
77e0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
77f0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7800: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7810: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7820: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
7830: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
7840: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
7850: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7860: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7870: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
7880: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
7890: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
78a0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
78b0: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
78c0: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
78d0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
78e0: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
78f0: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
7900: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7910: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
7920: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
7930: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
7940: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
7950: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7960: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7970: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
7980: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
7990: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
79a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
79b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
79c0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
79d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
79e0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
79f0: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
7a00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7a10: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
7a20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
7a30: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
7a40: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
7a50: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
7a60: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
7a70: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
7a80: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
7a90: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
7aa0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
7ab0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7ac0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7ad0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
7ae0: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
7af0: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
7b00: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
7b10: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
7b20: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
7b30: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
7b40: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
7b50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
7b60: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
7b70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7b80: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
7b90: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
7ba0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7bb0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
7bc0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
7bd0: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
7be0: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
7bf0: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
7c00: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
7c10: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7c20: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
7c30: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
7c40: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7c50: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7c60: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7c70: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
7c80: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
7c90: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7ca0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
7cb0: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
7cc0: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
7cd0: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
7ce0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
7cf0: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
7d00: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
7d10: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
7d20: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7d30: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
7d40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7d50: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
7d60: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7d70: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7d80: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
7d90: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
7da0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
7db0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
7dc0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
7dd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7de0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7df0: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
7e00: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7e10: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7e20: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7e30: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7e40: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7e50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7e60: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7e70: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7e80: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7e90: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
7ea0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7eb0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
7ec0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
7ed0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
7ee0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
7ef0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7f00: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7f10: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7f20: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7f30: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7f40: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7f50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7f60: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7f70: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7f80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7f90: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
7fa0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7fb0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
7fc0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
7fd0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
7fe0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
7ff0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8000: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8010: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
8020: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
8030: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
8040: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
8050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
8060: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8070: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
8080: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
8090: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
80a0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
80b0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
80c0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
80d0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
80e0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
80f0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
8100: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
8110: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
8120: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
8130: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
8140: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
8150: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
8160: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
8170: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
8180: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
8190: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
81a0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
81b0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
81c0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
81d0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
81e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
81f0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8200: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8210: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8220: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8230: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8240: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8250: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8260: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8270: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8280: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8290: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
82a0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
82b0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
82c0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
82d0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
82e0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
82f0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8300: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8310: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8320: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8330: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8340: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8350: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8360: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8370: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8380: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8390: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
83a0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
83b0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ems..**.** The [
83c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
83d0: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
83e0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
83f0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
8400: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
8410: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
8420: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
8430: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
8440: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
8450: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
8460: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8470: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
8480: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
8490: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
84a0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ..**.** ^(The [S
84b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
84c0: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
84d0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
84e0: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
84f0: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
8500: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
8510: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
8520: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
8530: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
8540: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8550: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8560: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8570: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
8580: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8590: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
85a0: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
85b0: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
85c0: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
85d0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
85e0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
85f0: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
8600: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
8610: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
8620: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
8630: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
8640: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
8650: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8660: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8670: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
8680: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
8690: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
86a0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
86b0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
86c0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
86d0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
86e0: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
86f0: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  re it.  .**.** ^
8700: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8710: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
8720: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8730: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
8740: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
8750: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
8760: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
8770: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
8780: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
8790: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
87a0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
87b0: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
87c0: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
87d0: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
87e0: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
87f0: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
8800: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
8810: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
8820: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
8830: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
8840: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
8850: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
8860: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
8870: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
8880: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
8890: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
88a0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
88b0: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
88c0: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
88d0: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
88e0: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
88f0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
8900: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
8910: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
8920: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
8930: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
8940: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
8950: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
8960: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
8970: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
8980: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
8990: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
89a0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
89b0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
89c0: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
89d0: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
89e0: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
89f0: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20  teger i the new 
8a00: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
8a10: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
8a20: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
8a30: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
8a40: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
8a50: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
8a60: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
8a70: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
8a80: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
8a90: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
8aa0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
8ab0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
8ac0: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
8ad0: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
8ae0: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
8af0: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
8b00: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
8b10: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
8b20: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
8b30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
8b40: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
8b50: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
8b60: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
8b70: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
8b80: 20 7c 20 57 72 69 74 65 20 41 48 65 61 64 20 4c   | Write AHead L
8b90: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
8ba0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
8bb0: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
8bc0: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
8bd0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
8be0: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
8bf0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
8c00: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
8c10: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
8c20: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
8c30: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
8c40: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
8c50: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
8c60: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8c70: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
8c80: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
8c90: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
8ca0: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
8cb0: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
8cc0: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
8cd0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
8ce0: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
8cf0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
8d00: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
8d10: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
8d20: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
8d30: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
8d40: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
8d50: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
8d60: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
8d70: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
8d80: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
8d90: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
8da0: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
8db0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
8dc0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8dd0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
8de0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
8df0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
8e00: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
8e10: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
8e20: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
8e30: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8e40: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
8e50: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
8e60: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
8e70: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
8e80: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
8e90: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
8ea0: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
8eb0: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
8ec0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
8ed0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
8ee0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
8ef0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8f00: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
8f10: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
8f20: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
8f30: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
8f40: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
8f50: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
8f60: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
8f70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
8f80: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
8f90: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
8fa0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8fb0: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
8fc0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
8fd0: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
8fe0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8ff0: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
9000: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
9010: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
9020: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
9030: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
9040: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
9050: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
9060: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
9070: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
9080: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
9090: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
90a0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
90b0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
90c0: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
90d0: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tting..**.** ^Th
90e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
90f0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9100: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
9110: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
9120: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
9130: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
9140: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
9150: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
9160: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
9170: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
9180: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
9190: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
91a0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
91b0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
91c0: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
91d0: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
91e0: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
91f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9200: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
9210: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
9220: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
9230: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
9240: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
9250: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
9260: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
9270: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
9280: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
9290: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
92a0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
92b0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
92c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
92d0: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
92e0: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
92f0: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
9300: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
9310: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9320: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
9330: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
9340: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
9350: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
9360: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
9370: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
9380: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
9390: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
93a0: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
93b0: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
93c0: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
93d0: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
93e0: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
93f0: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
9400: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
9410: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
9420: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
9430: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
9440: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
9450: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
9460: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9470: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
9480: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
9490: 73 65 20 6f 6e 6c 79 2e 0a 2a 2f 0a 23 64 65 66  se only..*/.#def
94a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
94b0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
94c0: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
94d0: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
94e0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
94f0: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
9500: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
9510: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
9520: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
9530: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
9540: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
9550: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
9560: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9570: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
9580: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
9590: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
95a0: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
95b0: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
95c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
95d0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
95e0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
95f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
9600: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
9610: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
9620: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9630: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
9640: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
9650: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9660: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
9670: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
9680: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
96a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
96b0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
96c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
96d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
96e0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
96f0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 0a  VERWRITE    13..
9700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9710: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
9720: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
9730: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
9740: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
9750: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
9760: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
9770: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
9780: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
9790: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
97a0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
97b0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
97c0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
97d0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
97e0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
97f0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
9800: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
9810: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
9820: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
9830: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
9840: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
9850: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
9860: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
9870: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
9880: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
9890: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
98a0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
98b0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
98c0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
98d0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
98e0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
98f0: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
9900: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
9910: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
9920: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
9930: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
9940: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
9950: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
9960: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
9970: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
9980: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
9990: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
99a0: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
99b0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
99c0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
99d0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
99e0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
99f0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
9a00: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
9a10: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
9a20: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
9a30: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
9a40: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
9a50: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
9a60: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
9a70: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
9a80: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
9a90: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
9aa0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
9ab0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
9ac0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
9ad0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
9ae0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
9af0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
9b00: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
9b10: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
9b20: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
9b30: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
9b40: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
9b50: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
9b60: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
9b70: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
9b80: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
9b90: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
9ba0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
9bb0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
9bc0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
9bd0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
9be0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
9bf0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
9c00: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
9c10: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
9c20: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
9c30: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
9c40: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
9c50: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
9c60: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
9c70: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
9c80: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
9c90: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
9ca0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
9cb0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
9cc0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
9cd0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
9ce0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
9cf0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
9d00: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
9d10: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
9d20: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
9d30: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
9d40: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
9d50: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
9d60: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
9d70: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
9d80: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
9d90: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
9da0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
9db0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
9dc0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
9dd0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
9de0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
9df0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
9e00: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
9e10: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
9e20: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
9e30: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
9e40: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
9e50: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
9e60: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
9e70: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
9e80: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
9e90: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
9ea0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
9eb0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
9ec0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
9ed0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
9ee0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
9ef0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
9f00: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
9f10: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
9f20: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
9f30: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
9f40: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
9f50: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
9f60: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
9f70: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
9f80: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
9f90: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
9fa0: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
9fb0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
9fc0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
9fd0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
9fe0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
9ff0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
a000: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
a010: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
a020: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
a030: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
a040: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
a050: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
a060: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
a070: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
a080: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
a090: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
a0a0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
a0b0: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
a0c0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
a0d0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
a0e0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
a0f0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
a100: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
a110: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
a120: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
a130: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
a140: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
a150: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
a160: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
a170: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
a180: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
a190: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
a1a0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
a1b0: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
a1c0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
a1d0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
a1e0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
a1f0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
a200: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
a210: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
a220: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
a230: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
a240: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
a250: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
a260: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
a270: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
a280: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
a290: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
a2a0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
a2b0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
a2c0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
a2d0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
a2e0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
a2f0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
a300: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
a310: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
a320: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
a330: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
a340: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
a350: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
a360: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
a370: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
a380: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
a390: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
a3a0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
a3b0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
a3c0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
a3d0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
a3e0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
a3f0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
a400: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
a410: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
a420: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
a430: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
a440: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
a450: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
a460: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
a470: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
a480: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
a490: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
a4a0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
a4b0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
a4c0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
a4d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
a4e0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
a4f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
a500: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
a510: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
a520: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
a530: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
a540: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
a550: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
a560: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
a570: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
a580: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
a590: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
a5a0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
a5b0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
a5c0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
a5d0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
a5e0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
a5f0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
a600: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
a610: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
a620: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
a630: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
a640: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
a650: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
a660: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
a670: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
a680: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
a690: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
a6a0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
a6b0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
a6c0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
a6d0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
a6e0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
a6f0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
a700: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
a710: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
a720: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
a730: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
a740: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
a750: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
a760: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
a770: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
a780: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
a790: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
a7a0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
a7b0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
a7c0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
a7d0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
a7e0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
a7f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
a800: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
a810: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
a820: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
a830: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
a840: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
a850: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
a860: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
a870: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
a880: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
a890: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
a8a0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
a8b0: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
a8c0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
a8d0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
a8e0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
a8f0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
a900: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
a910: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
a920: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
a930: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
a940: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
a950: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
a960: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
a970: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
a980: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
a990: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
a9a0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
a9b0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
a9c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
a9d0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
a9e0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
a9f0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
aa00: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
aa10: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
aa20: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
aa30: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
aa40: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
aa50: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
aa60: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
aa70: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
aa80: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
aa90: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
aaa0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
aab0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
aac0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
aad0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
aae0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
aaf0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
ab00: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
ab10: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
ab20: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
ab30: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
ab40: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
ab50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
ab60: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
ab70: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
ab80: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
ab90: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
aba0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
abb0: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
abc0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
abd0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
abe0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
abf0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
ac00: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
ac10: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
ac20: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
ac30: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
ac40: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
ac50: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
ac60: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
ac70: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
ac80: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
ac90: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
aca0: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
acb0: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
acc0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
acd0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
ace0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
acf0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
ad00: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
ad10: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
ad20: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
ad30: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
ad40: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
ad50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
ad60: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
ad70: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
ad80: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
ad90: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ada0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
adb0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
adc0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
add0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
ade0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
adf0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
ae00: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
ae10: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
ae20: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
ae30: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
ae40: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
ae50: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
ae60: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
ae70: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
ae80: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
ae90: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
aea0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
aeb0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
aec0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
aed0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
aee0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
aef0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
af00: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
af10: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
af20: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
af30: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
af40: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
af50: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
af60: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
af70: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
af80: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
af90: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
afa0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
afb0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
afc0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
afd0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
afe0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
aff0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
b000: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
b010: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
b020: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
b030: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
b040: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
b050: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
b060: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
b070: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
b080: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
b090: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
b0a0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
b0b0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
b0c0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
b0d0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
b0e0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
b0f0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
b100: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
b110: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
b120: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
b130: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
b140: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
b150: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
b160: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
b170: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
b180: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
b190: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
b1a0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
b1b0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
b1c0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
b1d0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
b1e0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
b1f0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
b200: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
b210: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
b220: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
b230: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
b240: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
b250: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
b260: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
b270: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
b280: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
b290: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
b2a0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
b2b0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
b2c0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
b2d0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
b2e0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
b2f0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
b300: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
b310: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
b320: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
b330: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
b340: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
b350: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
b360: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
b370: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
b380: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
b390: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
b3a0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
b3b0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
b3c0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
b3d0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
b3e0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
b3f0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
b400: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
b410: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
b420: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
b430: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
b440: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
b450: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
b460: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
b470: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
b480: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
b490: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
b4a0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
b4b0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
b4c0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
b4d0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
b4e0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
b4f0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
b500: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
b510: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
b520: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
b530: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
b540: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
b550: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
b560: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
b570: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
b580: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
b590: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
b5a0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
b5b0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
b5c0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
b5d0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
b5e0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
b5f0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
b600: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
b610: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
b620: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
b630: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
b640: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
b650: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
b660: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
b670: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
b680: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
b690: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
b6a0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
b6b0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
b6c0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
b6d0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
b6e0: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
b6f0: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
b700: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
b710: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
b720: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
b730: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
b740: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
b750: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
b760: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
b770: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
b780: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
b790: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
b7a0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
b7b0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
b7c0: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
b7d0: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
b7e0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
b7f0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
b800: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
b810: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
b820: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
b830: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
b840: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
b850: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
b860: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
b870: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
b880: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
b890: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
b8a0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
b8b0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
b8c0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
b8d0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
b8e0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
b8f0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
b900: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
b910: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
b920: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
b930: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
b940: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
b950: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
b960: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
b970: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
b980: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
b990: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
b9a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b9b0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
b9c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
b9d0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
b9e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b9f0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
ba00: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
ba10: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
ba20: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
ba30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ba40: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
ba50: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
ba60: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
ba70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ba80: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
ba90: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
baa0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
bab0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
bac0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
bad0: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
bae0: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
baf0: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
bb00: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
bb10: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
bb20: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
bb30: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
bb40: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
bb50: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
bb60: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
bb70: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
bb80: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
bb90: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
bba0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
bbb0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
bbc0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
bbd0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
bbe0: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
bbf0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
bc00: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
bc10: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
bc20: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
bc30: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
bc40: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
bc50: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
bc60: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
bc70: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
bc80: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
bc90: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
bca0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
bcb0: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
bcc0: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
bcd0: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
bce0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
bcf0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
bd00: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
bd10: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
bd20: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
bd30: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
bd40: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
bd50: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
bd60: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
bd70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
bd80: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
bd90: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
bda0: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
bdb0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
bdc0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
bdd0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
bde0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
bdf0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
be00: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
be10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
be20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
be30: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
be40: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
be50: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
be60: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
be70: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
be80: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
be90: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
bea0: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
beb0: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
bec0: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
bed0: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
bee0: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
bef0: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
bf00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
bf10: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
bf20: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
bf30: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
bf40: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
bf50: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
bf60: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
bf70: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
bf80: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
bf90: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
bfa0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
bfb0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
bfc0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
bfd0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
bfe0: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
bff0: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
c000: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
c010: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
c020: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
c030: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
c040: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
c050: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
c060: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
c070: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
c080: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
c090: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
c0a0: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
c0b0: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
c0c0: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
c0d0: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
c0e0: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
c0f0: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
c100: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
c110: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
c120: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
c130: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
c140: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
c150: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
c160: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
c170: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
c180: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
c190: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
c1a0: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
c1b0: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
c1c0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
c1d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
c1e0: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
c1f0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
c200: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
c210: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
c220: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
c230: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
c240: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
c250: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
c260: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
c270: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
c280: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
c290: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
c2a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
c2b0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
c2c0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
c2d0: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
c2e0: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
c2f0: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
c300: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
c310: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
c320: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
c330: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
c340: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
c350: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
c360: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
c370: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
c380: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
c390: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
c3a0: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
c3b0: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
c3c0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
c3d0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
c3e0: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
c3f0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
c400: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
c410: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
c420: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
c430: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
c440: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
c450: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
c460: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
c470: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
c480: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
c490: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
c4a0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
c4b0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
c4c0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
c4d0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
c4e0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
c4f0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
c500: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
c510: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
c520: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
c530: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
c540: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
c550: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
c560: 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65  was given no the
c570: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
c580: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
c590: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
c5a0: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
c5b0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
c5c0: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
c5d0: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
c5e0: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
c5f0: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
c600: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
c610: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
c620: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
c630: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
c640: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
c650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
c660: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
c670: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
c680: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
c690: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c6a0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
c6b0: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
c6c0: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
c6d0: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
c6e0: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
c6f0: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
c700: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
c710: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
c720: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
c730: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
c740: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
c750: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
c760: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
c770: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
c780: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
c790: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
c7a0: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
c7b0: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
c7c0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
c7d0: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
c7e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
c7f0: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
c800: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
c810: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
c820: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
c830: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
c840: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
c850: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
c860: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
c870: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
c880: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
c890: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
c8a0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
c8b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
c8c0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
c8d0: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
c8e0: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
c8f0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
c900: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
c910: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
c920: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
c930: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
c940: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
c950: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
c960: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
c970: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
c980: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
c990: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
c9a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
c9b0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
c9c0: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
c9d0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
c9e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c9f0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
ca00: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
ca10: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
ca20: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
ca30: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
ca40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ca50: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
ca60: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
ca70: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
ca80: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
ca90: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
caa0: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
cab0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
cac0: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
cad0: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
cae0: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
caf0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
cb00: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
cb10: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
cb20: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
cb30: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
cb40: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
cb50: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
cb60: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
cb70: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
cb80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
cb90: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
cba0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
cbb0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
cbc0: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
cbd0: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
cbe0: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
cbf0: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
cc00: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
cc10: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
cc20: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
cc30: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
cc40: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
cc50: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
cc60: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
cc70: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
cc80: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
cc90: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
cca0: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
ccb0: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
ccc0: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
ccd0: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
cce0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ccf0: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
cd00: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
cd10: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
cd20: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
cd30: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
cd40: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
cd50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
cd60: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
cd70: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
cd80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
cd90: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
cda0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
cdb0: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
cdc0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
cdd0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
cde0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
cdf0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
ce00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ce10: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
ce20: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
ce30: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
ce40: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
ce50: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
ce60: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
ce70: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
ce80: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
ce90: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
cea0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
ceb0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
cec0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
ced0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
cee0: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
cef0: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
cf00: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
cf10: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
cf20: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
cf30: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
cf40: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
cf50: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
cf60: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
cf70: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
cf80: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
cf90: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
cfa0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
cfb0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
cfc0: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
cfd0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
cfe0: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
cff0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d000: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
d010: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
d020: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
d030: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
d040: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
d050: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
d060: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
d070: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
d080: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
d090: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
d0a0: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
d0b0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
d0c0: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
d0d0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
d0e0: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
d0f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
d100: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
d110: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
d120: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
d130: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
d140: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d150: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
d160: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
d170: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
d180: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
d190: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
d1a0: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
d1b0: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
d1c0: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
d1d0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
d1e0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
d1f0: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
d200: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
d210: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
d220: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
d230: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
d240: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
d250: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
d260: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
d270: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
d280: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
d290: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
d2a0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
d2b0: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
d2c0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
d2d0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
d2e0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
d2f0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
d300: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
d310: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
d320: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
d330: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
d340: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
d350: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
d360: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
d370: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
d380: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
d390: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
d3a0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
d3b0: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
d3c0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
d3d0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
d3e0: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
d3f0: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
d400: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
d410: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
d420: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
d430: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
d440: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
d450: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
d460: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
d470: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
d480: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
d490: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
d4a0: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
d4b0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
d4c0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
d4d0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
d4e0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
d4f0: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
d500: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
d510: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
d520: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
d530: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
d540: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
d550: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d560: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
d570: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
d580: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
d590: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
d5a0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
d5b0: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
d5c0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
d5d0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
d5e0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
d5f0: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
d600: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
d610: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
d620: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
d630: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
d640: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
d650: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
d660: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
d670: 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
d680: 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
d690: 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
d6a0: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
d6b0: 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
d6c0: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
d6d0: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
d6e0: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
d6f0: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
d700: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
d710: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
d720: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
d730: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
d740: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
d750: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
d760: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
d770: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
d780: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
d790: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
d7a0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
d7b0: 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
d7c0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
d7d0: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
d7e0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
d7f0: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
d800: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
d810: 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
d820: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
d830: 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
d840: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
d850: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
d860: 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
d870: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d880: 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
d890: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
d8a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
d8b0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
d8c0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
d8d0: 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
d8e0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
d8f0: 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
d900: 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
d910: 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
d920: 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
d930: 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
d940: 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
d950: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
d960: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
d970: 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
d980: 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
d990: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
d9a0: 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
d9b0: 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
d9c0: 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
d9d0: 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
d9e0: 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
d9f0: 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
da00: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
da10: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
da20: 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
da30: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
da40: 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72  on.** must insur
da50: 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20  e that no other 
da60: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
da70: 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  s are invoked by
da80: 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64   other.** thread
da90: 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  s while sqlite3_
daa0: 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e  config() is runn
dab0: 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72  ing.  Furthermor
dac0: 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e, sqlite3_confi
dad0: 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  g().** may only 
dae0: 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
daf0: 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
db00: 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
db10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
db20: 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
db30: 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
db40: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
db50: 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
db60: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
db70: 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
db80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
db90: 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
dba0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
dbb0: 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
dbc0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
dbd0: 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
dbe0: 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
dbf0: 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
dc00: 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
dc10: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
dc20: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
dc30: 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
dc40: 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
dc50: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
dc60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
dc70: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
dc80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
dc90: 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
dca0: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
dcb0: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
dcc0: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
dcd0: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
dce0: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
dcf0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
dd00: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
dd10: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
dd20: 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
dd30: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
dd40: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
dd50: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
dd60: 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
dd70: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
dd80: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
dd90: 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
dda0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
ddb0: 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
ddc0: 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
ddd0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
dde0: 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
ddf0: 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
de00: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
de10: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
de20: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
de30: 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
de40: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
de50: 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
de60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
de70: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  s.**.** The sqli
de80: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
de90: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
dea0: 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
deb0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
dec0: 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
ded0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
dee0: 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
def0: 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
df00: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
df10: 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
df20: 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
df30: 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
df40: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
df50: 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
df60: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
df70: 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
df80: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
df90: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
dfa0: 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
dfb0: 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
dfc0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
dfd0: 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
dfe0: 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
dff0: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
e000: 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
e010: 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
e020: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
e030: 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
e040: 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
e050: 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
e060: 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
e070: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
e080: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
e090: 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
e0a0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
e0b0: 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
e0c0: 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
e0d0: 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
e0e0: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
e0f0: 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e  uccessful..*/.in
e100: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
e110: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
e120: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
e130: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
e140: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
e150: 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
e160: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
e170: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
e180: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
e190: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
e1a0: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
e1b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e1c0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
e1d0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
e1e0: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
e1f0: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
e200: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
e210: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
e220: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
e230: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
e240: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
e250: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e260: 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
e270: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e280: 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
e290: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
e2a0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
e2b0: 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
e2c0: 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
e2d0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
e2e0: 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
e2f0: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
e300: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
e310: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
e320: 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
e330: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
e340: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
e350: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
e360: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
e370: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
e380: 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
e390: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
e3a0: 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
e3b0: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
e3c0: 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
e3d0: 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
e3e0: 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
e3f0: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
e400: 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
e410: 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
e420: 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
e430: 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
e440: 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
e450: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
e460: 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
e470: 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
e480: 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
e490: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
e4a0: 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
e4b0: 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
e4c0: 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
e4d0: 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
e4e0: 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
e4f0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
e500: 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
e510: 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
e520: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
e530: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
e540: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
e550: 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
e560: 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
e570: 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
e580: 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
e590: 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
e5a0: 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
e5b0: 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
e5c0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
e5d0: 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
e5e0: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
e5f0: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
e600: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
e610: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
e620: 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
e630: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
e640: 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
e650: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
e660: 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
e670: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
e680: 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
e690: 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
e6a0: 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
e6b0: 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
e6c0: 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
e6d0: 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
e6e0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
e6f0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
e700: 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
e710: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
e720: 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
e730: 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
e740: 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
e750: 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
e760: 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
e770: 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
e780: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
e790: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
e7a0: 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
e7b0: 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
e7c0: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
e7d0: 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
e7e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
e7f0: 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
e800: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
e810: 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
e820: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
e830: 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
e840: 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
e850: 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
e860: 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
e870: 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
e880: 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
e890: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
e8a0: 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
e8b0: 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
e8c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
e8d0: 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
e8e0: 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
e8f0: 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
e900: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
e910: 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
e920: 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
e930: 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
e940: 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
e950: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
e960: 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
e970: 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
e980: 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
e990: 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
e9a0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
e9b0: 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
e9c0: 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
e9d0: 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
e9e0: 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
e9f0: 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
ea00: 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
ea10: 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
ea20: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
ea30: 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
ea40: 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
ea50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ea60: 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
ea70: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
ea80: 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
ea90: 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
eaa0: 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
eab0: 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
eac0: 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
ead0: 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
eae0: 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
eaf0: 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
eb00: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
eb10: 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
eb20: 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
eb30: 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
eb40: 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
eb50: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
eb60: 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
eb70: 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
eb80: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
eb90: 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
eba0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
ebb0: 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
ebc0: 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
ebd0: 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
ebe0: 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
ebf0: 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
ec00: 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
ec10: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
ec20: 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
ec30: 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
ec40: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
ec50: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
ec60: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ec70: 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
ec80: 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
ec90: 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
eca0: 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
ecb0: 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
ecc0: 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
ecd0: 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
ece0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
ecf0: 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
ed00: 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
ed10: 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
ed20: 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
ed30: 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
ed40: 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
ed50: 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
ed60: 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
ed70: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
ed80: 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
ed90: 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
eda0: 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
edb0: 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
edc0: 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
edd0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
ede0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
edf0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
ee00: 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
ee10: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
ee20: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
ee30: 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
ee40: 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
ee50: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ee60: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
ee70: 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
ee80: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
ee90: 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
eea0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
eeb0: 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
eec0: 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
eed0: 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
eee0: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
eef0: 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
ef00: 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
ef10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
ef20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
ef30: 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
ef40: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
ef50: 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
ef60: 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
ef70: 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
ef80: 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
ef90: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
efa0: 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
efb0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
efc0: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
efd0: 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
efe0: 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
eff0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
f000: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
f010: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
f020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
f030: 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
f040: 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
f050: 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
f060: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
f070: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
f080: 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
f090: 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
f0a0: 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
f0b0: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
f0c0: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
f0d0: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
f0e0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
f0f0: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
f100: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
f110: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
f120: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f130: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
f140: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
f150: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
f160: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
f170: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
f180: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
f190: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
f1a0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
f1b0: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
f1c0: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
f1d0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
f1e0: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
f1f0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
f200: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
f210: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
f220: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
f230: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
f240: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
f250: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
f260: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
f270: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
f280: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
f290: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
f2a0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
f2b0: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
f2c0: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
f2d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
f2e0: 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
f2f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
f300: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
f310: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
f320: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
f330: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
f340: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
f350: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
f360: 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
f370: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
f380: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
f390: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
f3a0: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
f3b0: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
f3c0: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
f3d0: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
f3e0: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
f3f0: 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
f400: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f410: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
f420: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
f430: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
f440: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
f450: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
f460: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
f470: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
f480: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
f490: 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
f4a0: 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
f4b0: 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
f4c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
f4d0: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
f4e0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
f4f0: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
f500: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
f510: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
f520: 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
f530: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
f540: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
f550: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
f560: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
f570: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
f580: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
f590: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
f5a0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
f5b0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
f5c0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
f5d0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
f5e0: 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
f5f0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
f600: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
f610: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
f620: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f630: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
f640: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
f650: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
f660: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
f670: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
f680: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
f690: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
f6a0: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
f6b0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
f6c0: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
f6d0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
f6e0: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
f6f0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
f700: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
f710: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
f720: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
f730: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
f740: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
f750: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
f760: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
f770: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
f780: 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
f790: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
f7a0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
f7b0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f7c0: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
f7d0: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
f7e0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
f7f0: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
f800: 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
f810: 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
f820: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
f830: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
f840: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
f850: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
f860: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
f870: 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
f880: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
f890: 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
f8a0: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
f8b0: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
f8c0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
f8d0: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
f8e0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
f8f0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
f900: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
f910: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
f920: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
f930: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
f940: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
f950: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
f960: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
f970: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
f980: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
f990: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
f9a0: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
f9b0: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
f9c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
f9d0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
f9e0: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
f9f0: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
fa00: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
fa10: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
fa20: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
fa30: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
fa40: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
fa50: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
fa60: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
fa70: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
fa80: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
fa90: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
faa0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
fab0: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
fac0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
fad0: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
fae0: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
faf0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
fb00: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
fb10: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
fb20: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
fb30: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
fb40: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
fb50: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
fb60: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
fb70: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
fb80: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
fb90: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
fba0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
fbb0: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
fbc0: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
fbd0: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
fbe0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
fbf0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
fc00: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
fc10: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
fc20: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
fc30: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
fc40: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
fc50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
fc60: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
fc70: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
fc80: 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
fc90: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
fca0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
fcb0: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
fcc0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
fcd0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
fce0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
fcf0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
fd00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
fd10: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
fd20: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
fd30: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
fd40: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
fd50: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
fd60: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
fd70: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
fd80: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
fd90: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fda0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
fdb0: 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
fdc0: 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
fdd0: 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
fde0: 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
fdf0: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
fe00: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
fe10: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
fe20: 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
fe30: 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
fe40: 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
fe50: 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
fe60: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
fe70: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
fe80: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
fe90: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
fea0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
feb0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
fec0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
fed0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
fee0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
fef0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
ff00: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
ff10: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
ff20: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
ff30: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
ff40: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
ff50: 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
ff60: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
ff70: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
ff80: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
ff90: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
ffa0: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
ffb0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
ffc0: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
ffd0: 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
ffe0: 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
fff0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
10000 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
10010 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
10020 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
10030 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
10040 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10050 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10060 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
10070 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
10080 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
10090 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
100a0 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
100b0 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
100c0 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
100d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
100e0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
100f0 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
10100 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
10110 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
10120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10130 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
10140 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
10150 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
10160 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
10170 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
10180 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
10190 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
101a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
101b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
101c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
101d0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
101e0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
101f0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
10200 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
10210 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
10220 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
10230 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10240 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
10250 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
10260 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
10270 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
10280 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
10290 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
102a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
102b0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
102c0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
102d0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
102e0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
102f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10300 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
10310 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10320 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
10330 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
10340 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
10350 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
10360 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
10370 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
10380 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
10390 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
103a0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
103b0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
103c0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
103d0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
103e0 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
103f0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
10400 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
10410 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
10420 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
10430 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
10440 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
10450 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
10460 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
10470 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
10480 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
10490 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
104a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
104b0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
104c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
104d0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
104e0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
104f0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
10500 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
10510 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
10520 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
10530 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
10540 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
10550 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
10560 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
10570 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
10580 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
10590 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
105a0 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
105b0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
105c0 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
105d0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
105e0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
105f0 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
10600 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
10610 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
10620 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
10630 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
10640 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
10650 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
10660 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
10670 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
10680 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
10690 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
106a0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
106b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
106c0 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
106d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
106e0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
106f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
10700 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
10710 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
10720 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
10730 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
10740 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
10750 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
10760 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
10770 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
10780 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
10790 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
107a0 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
107b0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
107c0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
107d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
107e0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
107f0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
10800 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
10810 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
10820 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
10830 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
10840 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
10850 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
10860 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
10870 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
10880 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
10890 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
108a0 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
108b0 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
108c0 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
108d0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
108e0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
108f0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
10900 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
10910 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
10920 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
10930 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
10940 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
10950 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
10960 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
10970 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
10980 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
10990 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
109a0 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
109b0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
109c0 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
109d0 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
109e0 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
109f0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
10a00 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
10a10 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
10a20 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
10a30 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
10a40 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
10a50 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
10a60 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
10a70 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
10a80 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
10a90 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
10aa0 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
10ab0 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
10ac0 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
10ad0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
10ae0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
10af0 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
10b00 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
10b10 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
10b20 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
10b30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
10b40 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
10b50 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
10b60 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
10b70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
10b80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
10b90 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
10ba0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
10bb0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
10bc0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
10bd0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
10be0 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
10bf0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10c00 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
10c10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10c20 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
10c30 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
10c40 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
10c50 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
10c60 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
10c70 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
10c80 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
10c90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10ca0 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
10cb0 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
10cc0 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
10cd0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
10ce0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
10cf0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
10d00 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
10d10 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
10d20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
10d30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
10d40 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
10d50 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
10d60 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
10d70 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
10d80 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
10d90 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
10da0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
10db0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
10dc0 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
10dd0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
10de0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
10df0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
10e00 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
10e10 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
10e20 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
10e30 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
10e40 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
10e50 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10e60 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
10e70 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
10e80 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
10e90 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
10ea0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
10eb0 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
10ec0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
10ed0 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
10ee0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
10ef0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
10f00 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
10f10 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
10f20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
10f30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
10f40 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
10f50 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
10f60 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
10f70 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
10f80 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
10f90 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
10fa0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
10fb0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
10fc0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
10fd0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
10fe0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
10ff0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
11000 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
11010 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
11020 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
11030 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
11040 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
11050 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11060 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
11070 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
11080 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
11090 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
110a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
110b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
110c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
110d0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
110e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
110f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
11100 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
11110 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
11120 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
11130 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
11140 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
11150 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
11160 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
11170 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
11180 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
11190 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
111a0 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
111b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
111c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
111d0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
111e0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
111f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11200 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
11210 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11220 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11230 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11240 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11250 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11260 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11270 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
11280 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
11290 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
112a0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
112b0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
112c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
112d0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
112e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
112f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11300 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
11310 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
11320 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
11330 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11340 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
11350 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11360 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
11370 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
11380 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
11390 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
113a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
113b0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
113c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
113d0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
113e0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
113f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11400 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
11410 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
11420 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
11430 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
11440 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
11450 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
11460 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
11470 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
11480 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
11490 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
114a0 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
114b0 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
114c0 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
114d0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
114e0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
114f0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
11500 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11510 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11520 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11530 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11540 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11550 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11560 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
11570 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
11580 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
11590 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
115a0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
115b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
115c0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
115d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
115e0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
115f0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
11600 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
11610 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
11620 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11630 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
11640 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11650 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
11660 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11670 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
11680 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
11690 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
116a0 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
116b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
116c0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
116d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
116e0 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
116f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
11700 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
11710 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
11720 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
11730 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
11740 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
11750 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
11760 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
11770 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
11780 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11790 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
117a0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
117b0 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
117c0 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
117d0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
117e0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
117f0 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
11800 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
11810 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
11820 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
11830 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
11840 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
11850 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
11860 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
11870 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
11880 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
11890 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
118a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
118b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
118c0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
118d0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
118e0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
118f0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
11900 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
11910 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
11920 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
11930 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
11940 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
11950 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
11960 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
11970 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
11980 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
11990 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
119a0 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
119b0 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
119c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
119d0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
119e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
119f0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
11a00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
11a10 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
11a20 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11a30 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
11a40 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
11a50 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
11a60 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
11a70 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
11a80 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
11a90 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
11aa0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
11ab0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
11ac0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11ad0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
11ae0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11af0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
11b00 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
11b10 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
11b20 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
11b30 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
11b40 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
11b50 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
11b60 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
11b70 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
11b80 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
11b90 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
11ba0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
11bb0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
11bc0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
11bd0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
11be0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
11bf0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
11c00 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
11c10 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
11c20 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
11c30 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
11c40 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
11c50 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
11c60 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
11c70 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
11c80 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
11c90 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
11ca0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
11cb0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
11cc0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
11cd0 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
11ce0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
11cf0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
11d00 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
11d10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
11d20 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
11d30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
11d40 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
11d50 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
11d60 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
11d70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
11d80 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
11d90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
11da0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
11db0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
11dc0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
11dd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
11de0 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
11df0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
11e00 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
11e10 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
11e20 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
11e30 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
11e40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
11e50 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
11e60 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
11e70 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
11e80 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
11e90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
11ea0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
11eb0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
11ec0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
11ed0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
11ee0 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
11ef0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
11f00 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
11f10 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
11f20 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
11f30 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11f40 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
11f50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
11f60 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
11f70 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
11f80 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
11f90 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
11fa0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
11fb0 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
11fc0 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
11fd0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
11fe0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
11ff0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
12000 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
12010 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
12020 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49  ally disabled. I
12030 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
12040 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
12050 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
12060 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b  s.** passed to [
12070 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
12080 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
12090 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  2()], [sqlite3_o
120a0 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
120b0 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
120c0 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
120d0 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
120e0 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
120f0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
12100 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
12110 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
12120 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
12130 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
12140 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
12150 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69   is opened. If i
12160 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
12170 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
12180 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
12190 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
121a0 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
121b0 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
121c0 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
121d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
121e0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
121f0 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
12200 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
12210 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
12220 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
12230 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
12240 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
12250 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
12260 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
12270 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  bol defined..**.
12280 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12290 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
122a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
122b0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
122c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
122d0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
122e0 4f 4e 46 4e 49 47 5f 47 45 54 50 43 41 43 48 45  ONFNIG_GETPCACHE
122f0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
12300 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
12310 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
12320 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
12330 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
12340 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
12350 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
12360 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
12370 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
12380 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
12390 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
123a0 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
123b0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
123c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
123d0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
123e0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
123f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12400 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
12410 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
12420 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12430 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
12440 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
12450 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
12460 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12470 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
12480 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
12490 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
124a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
124b0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
124c0 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
124d0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
124e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
124f0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12500 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
12510 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
12520 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12530 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
12540 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
12550 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
12560 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
12570 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12580 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
12590 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
125a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
125b0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
125c0 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
125d0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
125e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
125f0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
12600 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
12610 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
12620 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
12630 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
12640 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
12650 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
12660 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
12670 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12680 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
12690 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
126a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
126b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
126c0 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
126d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
126e0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
126f0 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
12700 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
12710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
12720 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
12730 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
12740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12750 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
12760 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
12770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12780 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
12790 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
127a0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
127b0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
127c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
127d0 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
127e0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
127f0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a  methods2* */../*
12800 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
12810 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
12820 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
12830 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
12840 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
12850 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
12860 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
12870 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
12880 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
12890 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
128a0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
128b0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
128c0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
128d0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
128e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
128f0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
12900 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
12910 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
12920 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
12930 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
12940 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
12950 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
12960 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
12970 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
12980 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
12990 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
129a0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
129b0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
129c0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
129d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
129e0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
129f0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
12a00 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
12a10 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
12a20 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
12a30 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
12a40 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
12a50 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
12a60 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
12a70 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
12a80 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
12a90 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
12aa0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
12ab0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
12ac0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
12ad0 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
12ae0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12af0 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
12b00 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
12b10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
12b20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
12b30 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
12b40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
12b50 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12b60 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
12b70 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
12b80 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
12b90 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
12ba0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
12bb0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
12bc0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
12bd0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
12be0 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
12bf0 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
12c00 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
12c10 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
12c20 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
12c30 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
12c40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
12c50 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
12c60 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
12c70 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
12c80 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
12c90 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
12ca0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
12cb0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
12cc0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
12cd0 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
12ce0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12cf0 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
12d00 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
12d10 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
12d20 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
12d30 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
12d40 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
12d50 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
12d60 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
12d70 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
12d80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12d90 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
12da0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
12db0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
12dc0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
12dd0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
12de0 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
12df0 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
12e00 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
12e10 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
12e20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
12e30 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
12e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12e50 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
12e60 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
12e70 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
12e80 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
12e90 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
12ea0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
12eb0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
12ec0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
12ed0 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
12ee0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
12ef0 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
12f00 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
12f10 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
12f20 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
12f30 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
12f40 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
12f50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
12f60 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
12f70 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
12f80 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
12f90 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
12fa0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
12fb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
12fc0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
12fd0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
12fe0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
12ff0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13000 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
13010 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
13020 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
13030 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
13040 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
13050 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
13060 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
13070 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
13080 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
13090 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
130a0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
130b0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
130c0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
130d0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
130e0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
130f0 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
13100 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
13110 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
13120 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
13130 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
13140 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
13150 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
13160 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
13170 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
13180 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
13190 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
131a0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
131b0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
131c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
131d0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
131e0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
131f0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
13200 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
13210 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
13220 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
13230 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
13240 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
13250 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
13260 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
13270 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
13280 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
13290 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
132a0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
132b0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
132c0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
132d0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
132e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
132f0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
13300 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
13310 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
13320 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
13330 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
13340 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
13350 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
13360 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
13370 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
13380 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
13390 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
133a0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
133b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
133c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
133d0 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
133e0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
133f0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
13400 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
13410 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13420 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
13430 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
13440 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
13450 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
13460 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
13470 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
13480 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
13490 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
134a0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
134b0 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69  1001  /* void* i
134c0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
134d0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
134e0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20  G_ENABLE_FKEY   
134f0 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69    1002  /* int i
13500 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
13510 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
13520 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31  NABLE_TRIGGER  1
13530 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  003  /* int int*
13540 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
13550 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
13560 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
13570 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
13580 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
13590 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
135a0 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
135b0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
135c0 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
135d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
135e0 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
135f0 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
13600 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
13610 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
13620 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
13630 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
13640 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e  atibility..*/.in
13650 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
13660 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
13670 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
13680 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
13690 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
136a0 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e  rt Rowid.**.** ^
136b0 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
136c0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
136d0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
136e0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
136f0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
13700 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
13710 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
13720 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
13730 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
13740 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
13750 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
13760 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
13770 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
13780 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
13790 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
137a0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
137b0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
137c0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
137d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
137e0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
137f0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
13800 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
13810 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
13820 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
13830 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
13840 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
13850 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
13860 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ent.** successfu
13870 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
13880 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
13890 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  m the [database 
138a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69  connection].** i
138b0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
138c0 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51  ment.  ^As of SQ
138d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
138e0 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .7, this routine
138f0 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65  s.** records the
13900 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77   last insert row
13910 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e  id of both ordin
13920 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b  ary tables and [
13930 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
13940 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
13950 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a  ssful [INSERT]s.
13960 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
13970 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61  urred on that da
13980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13990 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
139a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ned..**.** ^(If 
139b0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
139c0 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
139d0 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
139e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
139f0 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
13a00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
13a10 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
13a20 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
13a30 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
13a40 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
13a50 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
13a60 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
13a70 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
13a80 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
13a90 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
13aa0 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
13ab0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
13ac0 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
13ad0 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
13ae0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
13af0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
13b00 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
13b10 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
13b20 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
13b30 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
13b40 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
13b50 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
13b60 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
13b70 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
13b80 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
13b90 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
13ba0 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
13bb0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
13bc0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
13bd0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
13be0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
13bf0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
13c00 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
13c10 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
13c20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
13c30 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
13c40 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
13c50 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
13c60 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
13c70 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
13c80 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
13c90 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
13ca0 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
13cb0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
13cc0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
13cd0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
13ce0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
13cf0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
13d00 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
13d10 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
13d20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
13d30 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
13d40 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
13d50 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
13d60 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
13d70 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
13d80 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
13d90 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
13da0 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
13db0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
13dc0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
13dd0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
13de0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
13df0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
13e00 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
13e10 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
13e20 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
13e30 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
13e40 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
13e50 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
13e60 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
13e70 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
13e80 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
13e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
13ea0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
13eb0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
13ec0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
13ed0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
13ee0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
13ef0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
13f00 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
13f10 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
13f20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
13f30 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
13f40 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
13f50 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
13f60 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
13f70 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
13f80 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
13f90 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
13fa0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
13fb0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
13fc0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
13fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13fe0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
13ff0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
14000 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
14010 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
14020 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
14030 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
14040 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
14050 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
14060 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
14070 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
14080 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
14090 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
140a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
140b0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
140c0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
140d0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
140e0 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
140f0 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
14100 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
14110 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
14120 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
14130 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
14140 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
14150 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
14160 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
14170 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
14180 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
14190 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
141a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
141b0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
141c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
141d0 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
141e0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
141f0 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
14200 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
14210 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
14220 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
14230 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
14240 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
14250 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
14260 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
14270 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
14280 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
14290 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
142a0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
142b0 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
142c0 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
142d0 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
142e0 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
142f0 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
14300 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
14310 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
14320 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
14330 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
14340 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
14350 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
14360 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
14370 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
14380 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
14390 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
143a0 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
143b0 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
143c0 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
143d0 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
143e0 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
143f0 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
14400 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
14410 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
14420 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
14430 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
14440 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
14450 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
14460 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
14470 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
14480 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
14490 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
144a0 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
144b0 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
144c0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
144d0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
144e0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
144f0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
14500 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
14510 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
14520 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
14530 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
14540 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
14550 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
14560 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
14570 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
14580 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
14590 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
145a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
145b0 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
145c0 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
145d0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
145e0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
145f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
14600 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
14610 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
14620 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
14630 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
14640 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
14650 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
14660 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
14670 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
14680 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
14690 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
146a0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
146b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
146c0 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
146d0 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
146e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
146f0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
14700 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
14710 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
14720 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
14730 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
14740 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
14750 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
14760 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
14770 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
14780 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
14790 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
147a0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
147b0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
147c0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
147d0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
147e0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
147f0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
14800 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
14810 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
14820 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
14830 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
14840 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
14850 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
14860 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
14870 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
14880 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
14890 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
148a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
148b0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
148c0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
148d0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
148e0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
148f0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
14900 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
14910 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
14920 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
14930 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
14940 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
14950 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
14960 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
14970 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
14980 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
14990 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
149a0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
149b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
149c0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
149d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
149e0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
149f0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
14a00 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
14a10 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
14a20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
14a30 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
14a40 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
14a50 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
14a60 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
14a70 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
14a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14a90 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
14aa0 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
14ab0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
14ac0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
14ad0 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
14ae0 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
14af0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
14b00 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
14b10 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
14b20 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
14b30 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
14b40 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
14b50 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
14b60 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
14b70 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
14b80 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
14b90 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
14ba0 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
14bb0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
14bc0 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
14bd0 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
14be0 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
14bf0 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
14c00 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
14c10 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
14c20 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
14c30 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
14c40 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
14c50 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
14c60 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
14c70 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
14c80 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
14c90 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
14ca0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
14cb0 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
14cc0 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
14cd0 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
14ce0 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
14cf0 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
14d00 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
14d10 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
14d20 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
14d30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
14d40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
14d50 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
14d60 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
14d70 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
14d80 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
14d90 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
14da0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
14db0 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
14dc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
14dd0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
14de0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
14df0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
14e00 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
14e10 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
14e20 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
14e30 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
14e40 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
14e50 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
14e60 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
14e70 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
14e80 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
14e90 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
14ea0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
14eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14ec0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
14ed0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
14ee0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
14ef0 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
14f00 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
14f10 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
14f20 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
14f30 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
14f40 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
14f50 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
14f60 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
14f70 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
14f80 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
14f90 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
14fa0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
14fb0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
14fc0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
14fd0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
14fe0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
14ff0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
15000 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
15010 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
15020 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
15030 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
15040 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
15050 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
15060 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
15070 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
15080 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
15090 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
150a0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
150b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
150c0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
150d0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
150e0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
150f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
15100 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
15110 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
15120 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
15130 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
15140 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
15150 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
15160 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
15170 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
15180 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
15190 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
151a0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
151b0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
151c0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
151d0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
151e0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
151f0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
15200 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
15210 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
15220 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
15230 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
15240 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
15250 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
15260 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
15270 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
15280 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
15290 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
152a0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
152b0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
152c0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
152d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
152e0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
152f0 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
15300 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
15310 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
15320 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
15330 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15340 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
15350 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
15360 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
15370 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
15380 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
15390 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
153a0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
153b0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
153c0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
153d0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
153e0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
153f0 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
15400 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
15410 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
15420 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
15430 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
15440 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
15450 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
15460 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
15470 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
15480 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
15490 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
154a0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
154b0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
154c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
154d0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
154e0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
154f0 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
15500 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
15510 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
15520 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
15530 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
15540 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
15550 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
15560 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
15570 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
15580 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
15590 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
155a0 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
155b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
155c0 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
155d0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
155e0 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
155f0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
15600 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
15610 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
15620 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
15630 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
15640 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
15650 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
15660 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
15670 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
15680 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
15690 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
156a0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
156b0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
156c0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
156d0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
156e0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
156f0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
15700 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
15710 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
15720 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
15730 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
15740 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
15750 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
15760 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
15770 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
15780 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
15790 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
157a0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
157b0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
157c0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
157d0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
157e0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
157f0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
15800 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
15810 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
15820 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
15830 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
15840 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
15850 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
15860 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
15870 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
15880 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
15890 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
158a0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
158b0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
158c0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
158d0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
158e0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
158f0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
15900 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
15910 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
15920 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
15930 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
15940 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
15950 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
15960 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
15970 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
15980 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
15990 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
159a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
159b0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
159c0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
159d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
159e0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
159f0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
15a00 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
15a10 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
15a20 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
15a30 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
15a40 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
15a50 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
15a60 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
15a70 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
15a80 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
15a90 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
15aa0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
15ab0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
15ac0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
15ad0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
15ae0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
15af0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
15b00 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
15b10 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
15b20 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
15b30 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
15b40 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
15b50 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
15b60 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
15b70 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
15b80 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
15b90 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
15ba0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
15bb0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
15bc0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
15bd0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
15be0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
15bf0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
15c00 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
15c10 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
15c20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
15c30 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
15c40 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
15c50 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
15c60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
15c70 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
15c80 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
15c90 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
15ca0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
15cb0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
15cc0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
15cd0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
15ce0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
15cf0 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
15d00 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
15d10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
15d20 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
15d30 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
15d40 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
15d50 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
15d60 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
15d70 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
15d80 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
15d90 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
15da0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
15db0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
15dc0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
15dd0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
15de0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
15df0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
15e00 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
15e10 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
15e20 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
15e30 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
15e40 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
15e50 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
15e60 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
15e70 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
15e80 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
15e90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15ea0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
15eb0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
15ec0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
15ed0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
15ee0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
15ef0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
15f00 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
15f10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
15f20 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
15f30 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
15f40 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
15f50 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
15f60 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
15f70 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
15f80 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
15f90 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
15fa0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
15fb0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
15fc0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
15fd0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
15fe0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
15ff0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
16000 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
16010 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
16020 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
16030 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
16040 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
16050 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
16060 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
16070 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
16080 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
16090 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
160a0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
160b0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
160c0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
160d0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
160e0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
160f0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
16100 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
16110 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
16120 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
16130 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
16140 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
16150 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
16160 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
16170 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
16180 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
16190 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
161a0 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
161b0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
161c0 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
161d0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
161e0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
161f0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
16200 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
16210 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
16220 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
16230 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
16240 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
16250 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
16260 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
16270 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
16280 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
16290 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
162a0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
162b0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
162c0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
162d0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
162e0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
162f0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
16300 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
16310 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
16320 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
16330 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
16340 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
16350 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
16360 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
16370 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
16380 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
16390 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
163a0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
163b0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
163c0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
163d0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
163e0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
163f0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
16400 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
16410 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
16420 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
16430 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
16440 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
16450 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
16460 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
16470 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
16480 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
16490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
164a0 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
164b0 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
164c0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
164d0 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
164e0 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
164f0 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
16500 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
16510 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
16520 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
16530 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
16540 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
16550 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
16560 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
16570 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
16580 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
16590 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
165a0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
165b0 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
165c0 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
165d0 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
165e0 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
165f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
16600 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
16610 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
16620 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
16630 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
16640 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
16650 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
16660 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
16670 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
16680 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
16690 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
166a0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
166b0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
166c0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
166d0 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
166e0 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
166f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16700 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
16710 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
16720 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
16730 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
16740 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
16750 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
16760 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
16770 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
16780 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
16790 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
167a0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
167b0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
167c0 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
167d0 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
167e0 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
167f0 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
16800 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
16810 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
16820 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
16830 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
16840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
16850 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
16860 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
16870 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
16880 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
16890 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
168a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
168b0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
168c0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
168d0 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
168e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
168f0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
16900 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
16910 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
16920 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
16930 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
16940 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
16950 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
16960 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
16970 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
16980 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
16990 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
169a0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
169b0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
169c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
169d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
169e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
169f0 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
16a00 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
16a10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
16a20 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
16a30 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
16a40 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
16a50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16a60 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
16a70 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
16a80 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
16a90 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
16aa0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
16ab0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
16ac0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
16ad0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
16ae0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
16af0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
16b00 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
16b10 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
16b20 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
16b30 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
16b40 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
16b50 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
16b60 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
16b70 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
16b80 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
16b90 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
16ba0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
16bb0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
16bc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
16bd0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
16be0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
16bf0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
16c00 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
16c10 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
16c20 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
16c30 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
16c40 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
16c50 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
16c60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
16c70 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
16c80 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
16c90 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
16ca0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
16cb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
16cc0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
16cd0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
16ce0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
16cf0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
16d00 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
16d10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
16d20 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
16d30 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
16d40 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
16d50 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
16d60 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
16d70 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
16d80 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
16d90 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
16da0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16db0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
16dc0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
16dd0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
16de0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
16df0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
16e00 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
16e10 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
16e20 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
16e30 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
16e40 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
16e50 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
16e60 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
16e70 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
16e80 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
16e90 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
16ea0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
16eb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
16ec0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
16ed0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
16ee0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
16ef0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
16f00 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
16f10 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
16f20 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
16f30 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
16f40 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
16f50 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
16f60 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
16f70 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
16f80 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
16f90 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
16fa0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
16fb0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
16fc0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
16fd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
16fe0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
16ff0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
17000 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
17010 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
17020 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
17030 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
17040 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
17050 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
17060 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
17070 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
17080 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
17090 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
170a0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
170b0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
170c0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
170d0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
170e0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
170f0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
17100 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
17110 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
17120 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
17130 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
17140 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
17150 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
17160 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
17170 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
17180 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
17190 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
171a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
171b0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
171c0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
171d0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
171e0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
171f0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
17200 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
17210 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
17220 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
17230 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
17240 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
17250 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
17260 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
17270 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
17280 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
17290 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
172a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
172b0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
172c0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
172d0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
172e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
172f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
17300 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
17310 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
17320 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
17330 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
17340 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
17350 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
17360 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
17370 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
17380 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
17390 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
173a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
173b0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
173c0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
173d0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
173e0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
173f0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
17400 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
17410 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
17420 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
17430 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
17440 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
17450 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
17460 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
17470 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
17480 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
17490 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
174a0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
174b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
174c0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
174d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
174e0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
174f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
17500 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
17510 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
17520 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
17530 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
17540 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
17550 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
17560 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
17570 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
17580 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
17590 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
175a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
175b0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
175c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
175d0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
175e0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
175f0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
17600 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
17610 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
17620 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
17630 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
17640 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
17650 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
17660 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
17670 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
17680 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
17690 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
176a0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
176b0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
176c0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
176d0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
176e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
176f0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
17700 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
17710 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
17720 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
17730 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
17740 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
17750 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
17760 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
17770 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
17780 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
17790 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
177a0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
177b0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
177c0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
177d0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
177e0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
177f0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
17800 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
17810 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
17820 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
17830 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
17840 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
17850 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
17860 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
17870 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
17880 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
17890 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
178a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
178b0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
178c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
178d0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
178e0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
178f0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
17900 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
17910 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
17920 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
17930 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
17940 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
17950 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
17960 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
17970 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
17980 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
17990 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
179a0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
179b0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
179c0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
179d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
179e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
179f0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
17a00 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
17a10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
17a20 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
17a30 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
17a40 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
17a50 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
17a60 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
17a70 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
17a80 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
17a90 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
17aa0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
17ab0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
17ac0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
17ad0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
17ae0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
17af0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
17b00 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
17b10 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
17b20 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
17b30 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
17b40 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
17b50 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
17b60 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
17b70 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
17b80 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
17b90 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
17ba0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
17bb0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
17bc0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
17bd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
17be0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
17bf0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
17c00 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
17c10 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
17c20 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
17c30 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
17c40 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
17c50 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
17c60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
17c70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
17c80 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
17c90 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
17ca0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
17cb0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
17cc0 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
17cd0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
17ce0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
17cf0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
17d00 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
17d10 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
17d20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
17d30 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
17d40 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
17d50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
17d60 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
17d70 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
17d80 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
17d90 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
17da0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
17db0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
17dc0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
17dd0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
17de0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
17df0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
17e00 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
17e10 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
17e20 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
17e30 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
17e40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17e50 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
17e60 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
17e70 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
17e80 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
17e90 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
17ea0 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
17eb0 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
17ec0 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
17ed0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
17ee0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
17ef0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
17f00 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
17f10 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
17f20 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
17f30 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
17f40 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
17f50 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
17f60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
17f70 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
17f80 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
17f90 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
17fa0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
17fb0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
17fc0 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
17fd0 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
17fe0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
17ff0 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
18000 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
18010 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
18020 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
18030 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
18040 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
18050 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
18060 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
18070 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
18080 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
18090 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
180a0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
180b0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
180c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
180d0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
180e0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
180f0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
18100 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
18110 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
18120 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
18130 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
18140 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
18150 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
18160 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
18170 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
18180 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
18190 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
181a0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
181b0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
181c0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
181d0 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
181e0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
181f0 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
18200 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
18210 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
18220 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
18230 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
18240 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
18250 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
18260 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
18270 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
18280 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
18290 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
182a0 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
182b0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
182c0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
182d0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
182e0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
182f0 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
18300 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
18310 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
18320 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
18330 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
18340 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
18350 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
18360 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
18370 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
18380 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
18390 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
183a0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
183b0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
183c0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
183d0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
183e0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
183f0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
18400 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
18410 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
18420 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
18430 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
18440 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
18450 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
18460 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
18470 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
18480 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
18490 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
184a0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
184b0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
184c0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
184d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
184e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
184f0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
18500 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
18510 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
18520 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
18530 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
18540 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
18550 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
18560 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
18570 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
18580 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
18590 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
185a0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
185b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
185c0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
185d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
185e0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
185f0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
18600 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
18610 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
18620 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
18630 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
18640 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
18650 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
18660 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
18670 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
18680 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
18690 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
186a0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
186b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
186c0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
186d0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
186e0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
186f0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
18700 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
18710 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
18720 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
18730 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
18740 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
18750 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
18760 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
18770 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18780 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
18790 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
187a0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
187b0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
187c0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
187d0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
187e0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
187f0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
18800 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
18810 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
18820 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
18830 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
18840 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
18850 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
18860 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
18870 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
18880 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
18890 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
188a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
188b0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
188c0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
188d0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
188e0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
188f0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
18900 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
18910 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
18920 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
18930 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
18940 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18950 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
18960 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
18970 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
18980 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
18990 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
189a0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
189b0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
189c0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
189d0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
189e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
189f0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
18a00 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
18a10 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
18a20 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
18a30 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
18a40 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
18a50 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
18a60 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
18a70 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
18a80 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
18a90 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
18aa0 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
18ab0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
18ac0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
18ad0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
18ae0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
18af0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
18b00 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
18b10 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
18b20 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
18b30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
18b40 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
18b50 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
18b60 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
18b70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
18b80 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
18b90 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
18ba0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
18bb0 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  r*, ...);.char *
18bc0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
18bd0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
18be0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
18bf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18c00 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
18c10 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
18c20 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
18c30 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
18c40 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
18c50 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
18c60 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
18c70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18c80 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
18c90 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
18ca0 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
18cb0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
18cc0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
18cd0 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
18ce0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
18cf0 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
18d00 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
18d10 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
18d20 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
18d30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
18d40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
18d50 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
18d60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
18d70 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
18d80 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
18d90 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
18da0 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
18db0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
18dc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
18dd0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
18de0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
18df0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
18e00 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
18e10 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
18e20 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
18e30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
18e40 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
18e50 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
18e60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
18e70 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
18e80 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
18e90 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
18ea0 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
18eb0 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
18ec0 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
18ed0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
18ee0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
18ef0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
18f00 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
18f10 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
18f20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
18f30 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
18f40 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
18f50 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
18f60 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
18f70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
18f80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
18f90 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
18fa0 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
18fb0 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
18fc0 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
18fd0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
18fe0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
18ff0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
19000 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
19010 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
19020 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
19030 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
19040 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
19050 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
19060 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
19070 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
19080 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
19090 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
190a0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
190b0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
190c0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
190d0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
190e0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
190f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
19100 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
19110 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
19120 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
19130 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19140 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
19150 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
19160 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
19170 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
19180 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
19190 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
191a0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
191b0 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
191c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
191d0 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
191e0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
191f0 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
19200 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19210 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
19220 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
19230 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
19240 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
19250 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
19260 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
19270 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
19280 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
19290 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
192a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
192b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
192c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
192d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
192e0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
192f0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
19300 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
19310 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
19320 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
19330 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
19340 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
19350 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
19360 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19370 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
19380 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
19390 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
193a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
193b0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
193c0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
193d0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
193e0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
193f0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
19400 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
19410 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
19420 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
19430 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
19440 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
19450 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
19460 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
19470 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
19480 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
19490 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
194a0 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
194b0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
194c0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
194d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
194e0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
194f0 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
19500 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
19510 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
19520 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
19530 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
19540 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
19550 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
19560 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
19570 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
19580 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
19590 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
195a0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
195b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
195c0 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
195d0 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
195e0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
195f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
19600 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
19610 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
19620 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
19630 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
19640 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
19650 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
19660 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
19670 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
19680 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
19690 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
196a0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
196b0 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
196c0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
196d0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
196e0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
196f0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
19700 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
19710 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
19720 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
19730 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
19740 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
19750 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
19760 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
19770 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
19780 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
19790 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
197a0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
197b0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
197c0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
197d0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
197e0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
197f0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
19800 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
19810 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
19820 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
19830 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
19840 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
19850 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
19860 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
19870 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
19880 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
19890 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
198a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
198b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
198c0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
198d0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
198e0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
198f0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
19900 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
19910 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
19920 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
19930 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
19940 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
19950 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
19960 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
19970 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
19980 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
19990 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
199a0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
199b0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
199c0 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
199d0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
199e0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
199f0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
19a00 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
19a10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
19a20 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
19a30 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
19a40 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
19a50 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
19a60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19a70 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
19a80 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
19a90 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
19aa0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
19ab0 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
19ac0 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
19ad0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
19ae0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19af0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
19b00 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
19b10 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
19b20 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
19b30 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
19b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19b50 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
19b60 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
19b70 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
19b80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
19b90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
19ba0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
19bb0 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
19bc0 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
19bd0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
19be0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
19bf0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
19c00 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
19c10 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
19c20 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
19c30 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
19c40 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
19c50 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
19c60 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
19c70 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
19c80 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
19c90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
19ca0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
19cb0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
19cc0 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
19cd0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
19ce0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
19cf0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
19d00 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
19d10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
19d20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
19d30 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
19d40 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
19d50 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
19d60 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
19d70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19d80 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
19d90 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
19da0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
19db0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
19dc0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
19dd0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
19de0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
19df0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
19e00 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
19e10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
19e20 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
19e30 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
19e40 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
19e50 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
19e60 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
19e70 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
19e80 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
19e90 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
19ea0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
19eb0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
19ec0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
19ed0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
19ee0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
19ef0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
19f00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
19f10 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
19f20 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
19f30 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
19f40 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
19f50 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
19f60 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
19f70 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
19f80 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
19f90 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
19fa0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
19fb0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
19fc0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
19fd0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
19fe0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
19ff0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
1a000 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
1a010 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
1a020 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
1a030 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
1a040 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
1a050 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1a060 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
1a070 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
1a080 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
1a090 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
1a0a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
1a0b0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1a0c0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
1a0d0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
1a0e0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
1a0f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
1a100 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
1a110 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
1a120 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
1a130 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
1a140 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
1a150 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
1a160 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
1a170 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
1a180 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1a190 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
1a1a0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1a1b0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
1a1c0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
1a1d0 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
1a1e0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1a1f0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1a200 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1a210 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1a220 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1a230 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1a240 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1a250 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
1a260 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1a270 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1a280 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1a290 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1a2a0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1a2b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1a2c0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1a2d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a2e0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1a2f0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1a300 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1a310 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1a320 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1a330 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1a340 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1a350 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1a360 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1a370 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1a380 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1a390 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1a3a0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1a3b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1a3c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1a3d0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1a3e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1a3f0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1a400 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1a410 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1a420 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1a430 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1a440 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1a450 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1a460 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1a470 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1a480 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1a490 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1a4a0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1a4b0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1a4c0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1a4d0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1a4e0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1a4f0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1a500 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1a510 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1a520 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1a530 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1a540 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1a550 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1a560 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1a570 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1a580 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1a590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1a5a0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1a5b0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1a5c0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1a5d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1a5e0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1a5f0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1a600 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1a610 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1a620 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1a630 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1a640 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1a650 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1a660 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1a670 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1a680 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1a690 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1a6a0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1a6b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1a6c0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1a6d0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1a6e0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1a6f0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1a700 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1a710 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1a720 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1a730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a740 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1a750 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1a760 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1a770 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1a780 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1a790 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1a7a0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1a7b0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1a7c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1a7d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a7e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a7f0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1a800 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1a810 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a820 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1a830 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1a840 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1a850 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1a860 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1a870 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1a880 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1a890 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1a8a0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1a8b0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1a8c0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1a8d0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1a8e0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1a8f0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1a900 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1a910 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a920 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1a930 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1a940 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1a950 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1a960 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1a970 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1a980 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1a990 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1a9a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a9b0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1a9c0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1a9d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a9e0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1a9f0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1aa00 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1aa10 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1aa20 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1aa30 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1aa40 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1aa50 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1aa60 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1aa70 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1aa80 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1aa90 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1aaa0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1aab0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1aac0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1aad0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1aae0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1aaf0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1ab00 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1ab10 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1ab20 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1ab30 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1ab40 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1ab50 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1ab60 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1ab70 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1ab80 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1ab90 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1aba0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1abb0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1abc0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1abd0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1abe0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1abf0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1ac00 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1ac10 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1ac20 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1ac30 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1ac40 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1ac50 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1ac60 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1ac70 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1ac80 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1ac90 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1aca0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1acb0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1acc0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1acd0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1ace0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1acf0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1ad00 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1ad10 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1ad20 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1ad30 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1ad40 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1ad50 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1ad60 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1ad70 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1ad80 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1ad90 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1ada0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1adb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1adc0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1add0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1ade0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1adf0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1ae00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1ae10 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1ae20 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1ae30 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1ae40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1ae50 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1ae60 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1ae70 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1ae80 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1ae90 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1aea0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1aeb0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1aec0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1aed0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1aee0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1aef0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1af00 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1af10 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1af20 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1af30 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1af40 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1af50 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1af60 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1af70 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1af80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1af90 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1afa0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1afb0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1afc0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1afd0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1afe0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1aff0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1b000 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1b010 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1b020 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1b030 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1b040 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1b050 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b060 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1b070 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1b080 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1b090 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b0a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1b0b0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1b0c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1b0d0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1b0e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b0f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1b100 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1b110 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1b120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1b130 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1b140 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1b150 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1b160 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1b170 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b180 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1b190 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1b1a0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1b1b0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1b1c0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1b1d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b1e0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1b1f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1b200 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1b210 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1b220 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1b230 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1b240 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1b250 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1b260 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1b270 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1b280 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1b290 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b2a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1b2b0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1b2c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1b2d0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1b2e0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1b2f0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1b300 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1b310 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1b320 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1b330 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1b340 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1b350 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1b360 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1b370 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1b380 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1b390 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1b3a0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1b3b0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1b3c0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1b3d0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1b3e0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1b3f0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1b400 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1b410 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1b420 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1b430 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1b440 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1b450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1b460 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1b470 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1b480 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1b490 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1b4a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1b4b0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1b4c0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1b4d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1b4e0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1b4f0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1b500 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1b510 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1b520 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1b530 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1b540 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1b550 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1b560 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1b570 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1b580 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1b590 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1b5a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1b5b0 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1b5c0 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1b5d0 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1b5e0 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1b5f0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1b600 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1b610 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1b620 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1b630 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1b640 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1b650 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1b660 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1b670 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1b680 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1b690 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1b6a0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1b6b0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1b6c0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1b6d0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1b6e0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1b6f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1b700 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1b710 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1b720 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1b730 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1b740 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1b750 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1b760 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1b770 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1b780 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1b790 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1b7a0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1b7b0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1b7c0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1b7d0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1b7e0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1b7f0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1b800 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1b810 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b820 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1b830 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1b840 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1b850 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1b860 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1b870 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1b880 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1b890 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1b8a0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1b8b0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1b8c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1b8d0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1b8e0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1b8f0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1b900 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1b910 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1b920 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1b930 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1b940 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1b950 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1b960 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1b970 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1b980 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1b990 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1b9a0 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1b9b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1b9c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b9d0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1b9e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1b9f0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1ba00 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1ba10 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1ba20 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1ba30 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1ba40 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1ba50 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1ba60 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1ba70 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1ba80 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1ba90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1baa0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1bab0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1bac0 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1bad0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1bae0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1baf0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1bb00 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1bb10 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1bb20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1bb30 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1bb40 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1bb50 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1bb60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1bb70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1bb80 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1bb90 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1bba0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1bbb0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1bbc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1bbd0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1bbe0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1bbf0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1bc00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1bc10 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1bc20 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1bc30 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1bc40 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1bc50 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1bc60 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1bc70 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1bc80 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1bc90 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1bca0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1bcb0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1bcc0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1bcd0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1bce0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1bcf0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1bd00 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1bd10 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1bd20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1bd30 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1bd40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1bd50 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1bd60 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1bd70 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bd80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1bd90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bda0 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1bdb0 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1bdc0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1bdd0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1bde0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1bdf0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1be00 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1be10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1be20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1be30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1be40 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1be50 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1be60 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1be70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1be80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1be90 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1bea0 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1beb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1bec0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1bed0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bee0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1bef0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1bf00 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1bf10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1bf20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bf30 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1bf40 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1bf50 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1bf60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1bf70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bf80 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1bf90 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1bfa0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1bfb0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1bfc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1bfd0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1bfe0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1bff0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1c000 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1c010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1c020 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1c030 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1c040 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1c050 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1c060 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1c070 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1c080 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1c090 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1c0a0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1c0b0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1c0c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c0d0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1c0e0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1c0f0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1c100 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1c110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1c120 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1c130 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1c140 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1c150 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1c160 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1c170 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1c180 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c190 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c1a0 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1c1b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1c1c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1c1d0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1c1e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c1f0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1c200 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1c210 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1c220 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c230 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c240 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1c250 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1c260 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1c270 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c280 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c290 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1c2a0 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1c2b0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1c2c0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1c2d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c2e0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1c2f0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1c300 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1c310 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c330 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1c340 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1c350 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c360 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c370 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c380 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1c390 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1c3a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1c3b0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1c3c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c3d0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1c3e0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1c3f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1c400 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1c410 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c420 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1c430 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1c440 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1c450 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1c460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1c470 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1c480 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1c490 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1c4a0 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1c4b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1c4c0 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1c4d0 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1c4e0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
1c4f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
1c500 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
1c510 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1c520 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1c530 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
1c540 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1c550 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
1c560 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
1c570 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
1c580 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
1c590 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1c5a0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1c5b0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1c5c0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1c5d0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1c5e0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1c5f0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1c600 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1c610 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1c620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1c630 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c640 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1c650 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
1c660 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1c670 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
1c680 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1c690 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
1c6a0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
1c6b0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
1c6c0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
1c6d0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1c6e0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
1c6f0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1c700 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1c710 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1c720 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1c730 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1c740 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1c750 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1c760 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1c770 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
1c780 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c790 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1c7a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1c7b0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1c7c0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
1c7d0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
1c7e0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1c7f0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
1c800 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
1c810 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1c820 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
1c830 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
1c840 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
1c850 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1c860 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
1c870 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1c880 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
1c890 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
1c8a0 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
1c8b0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
1c8c0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
1c8d0 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
1c8e0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
1c8f0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
1c900 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
1c910 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
1c920 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
1c930 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
1c940 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1c950 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
1c960 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
1c970 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
1c980 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
1c990 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
1c9a0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
1c9b0 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
1c9c0 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1c9d0 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
1c9e0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
1c9f0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
1ca00 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1ca10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1ca20 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1ca30 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1ca40 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1ca50 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
1ca60 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1ca70 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
1ca80 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
1ca90 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
1caa0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1cab0 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
1cac0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1cad0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
1cae0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
1caf0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
1cb00 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1cb10 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
1cb20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1cb30 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
1cb40 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
1cb50 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
1cb60 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1cb70 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
1cb80 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1cb90 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1cba0 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
1cbb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1cbc0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
1cbd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1cbe0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
1cbf0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1cc00 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1cc10 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1cc20 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1cc30 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
1cc40 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
1cc50 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1cc60 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
1cc70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
1cc80 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1cc90 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
1cca0 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
1ccb0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1ccc0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1ccd0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1cce0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1ccf0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1cd00 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1cd10 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1cd20 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  k X..**.** ^Only
1cd30 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1cd40 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1cd50 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1cd60 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1cd70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cd80 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1cd90 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1cda0 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1cdb0 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1cdc0 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1cdd0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1cde0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1cdf0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1ce00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1ce10 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1ce20 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1ce30 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1ce40 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1ce50 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1ce60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ce70 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1ce80 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1ce90 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1cea0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1ceb0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1cec0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1ced0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1cee0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1cef0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1cf00 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1cf10 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1cf20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1cf30 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1cf40 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1cf50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1cf60 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1cf70 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1cf80 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1cf90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cfa0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1cfb0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1cfc0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1cfd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cfe0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1cff0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1d000 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1d010 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
1d020 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1d030 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1d040 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
1d050 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1d060 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
1d070 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
1d080 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
1d090 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1d0a0 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1d0b0 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1d0c0 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
1d0d0 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
1d0e0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
1d0f0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1d100 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1d110 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1d120 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1d130 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1d140 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1d150 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1d160 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1d170 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1d180 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
1d190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d1a0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
1d1b0 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
1d1c0 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
1d1d0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1d1e0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
1d1f0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
1d200 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
1d210 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1d220 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1d230 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1d240 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
1d250 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
1d260 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
1d270 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
1d280 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
1d290 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
1d2a0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1d2b0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
1d2c0 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
1d2d0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
1d2e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1d2f0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
1d300 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1d310 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1d320 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
1d330 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1d340 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1d350 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1d360 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1d370 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1d380 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1d390 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1d3a0 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
1d3b0 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
1d3c0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
1d3d0 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
1d3e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
1d3f0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
1d400 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
1d410 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
1d420 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
1d430 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1d440 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
1d450 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
1d460 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1d470 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
1d480 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
1d490 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
1d4a0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
1d4b0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
1d4c0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
1d4d0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
1d4e0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1d4f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1d500 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
1d510 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
1d520 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
1d530 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
1d540 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
1d550 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1d560 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1d570 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d580 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
1d590 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
1d5a0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
1d5b0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
1d5c0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
1d5d0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
1d5e0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
1d5f0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
1d600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d610 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
1d620 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
1d630 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
1d640 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
1d650 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1d660 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1d670 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1d680 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1d690 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d6a0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
1d6b0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1d6c0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1d6d0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
1d6e0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1d6f0 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
1d700 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1d710 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
1d720 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
1d730 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1d740 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
1d750 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1d760 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
1d770 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
1d780 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
1d790 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
1d7a0 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
1d7b0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d7c0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1d7d0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1d7e0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
1d7f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1d800 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1d810 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1d820 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
1d830 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
1d840 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
1d850 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
1d860 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
1d870 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
1d880 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
1d890 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
1d8a0 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
1d8b0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
1d8c0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1d8d0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1d8e0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1d8f0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1d900 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1d910 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1d920 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1d930 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1d940 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1d950 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1d960 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
1d970 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
1d980 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
1d990 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
1d9a0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
1d9b0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1d9c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1d9d0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
1d9e0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
1d9f0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
1da00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1da10 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
1da20 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
1da30 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
1da40 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
1da50 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
1da60 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
1da70 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
1da80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
1da90 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
1daa0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
1dab0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
1dac0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1dad0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1dae0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1daf0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1db00 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1db10 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1db20 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1db30 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1db40 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1db50 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1db60 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1db70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1db80 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
1db90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1dba0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1dbb0 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1dbc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dbd0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1dbe0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1dbf0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1dc00 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1dc10 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1dc20 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1dc30 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1dc40 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1dc50 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
1dc60 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1dc70 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1dc80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1dc90 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
1dca0 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
1dcb0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1dcc0 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
1dcd0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1dce0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
1dcf0 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
1dd00 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1dd10 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1dd20 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
1dd30 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1dd40 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1dd50 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1dd60 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
1dd70 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
1dd80 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
1dd90 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
1dda0 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
1ddb0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
1ddc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1ddd0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1dde0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1ddf0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
1de00 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
1de10 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
1de20 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1de30 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
1de40 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1de50 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
1de60 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
1de70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1de80 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
1de90 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
1dea0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1deb0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
1dec0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
1ded0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
1dee0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1def0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1df00 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
1df10 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
1df20 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1df30 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
1df40 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1df50 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1df60 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1df70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1df80 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1df90 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1dfa0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1dfb0 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1dfc0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1dfd0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1dfe0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1dff0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1e000 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1e010 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1e020 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1e030 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1e040 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1e050 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1e060 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1e070 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1e080 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1e090 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1e0a0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1e0b0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1e0c0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
1e0d0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1e0e0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1e0f0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
1e100 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1e110 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
1e120 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
1e130 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
1e140 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
1e150 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
1e160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e170 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
1e180 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
1e190 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
1e1a0 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
1e1b0 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
1e1c0 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
1e1d0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
1e1e0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1e1f0 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
1e200 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
1e210 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
1e220 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
1e230 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
1e240 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
1e250 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
1e260 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1e270 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
1e280 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
1e290 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
1e2a0 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
1e2b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1e2c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
1e2d0 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
1e2e0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
1e2f0 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
1e300 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
1e310 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
1e320 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1e330 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
1e340 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
1e350 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
1e360 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
1e370 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
1e380 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
1e390 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
1e3a0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
1e3b0 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
1e3c0 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
1e3d0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
1e3e0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
1e3f0 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
1e400 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
1e410 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
1e420 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
1e430 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
1e440 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1e450 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
1e460 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
1e470 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
1e480 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
1e490 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
1e4a0 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
1e4b0 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
1e4c0 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
1e4d0 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
1e4e0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
1e4f0 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
1e500 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
1e510 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1e520 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
1e530 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
1e540 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
1e550 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
1e560 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
1e570 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
1e580 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
1e590 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
1e5a0 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
1e5b0 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
1e5c0 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
1e5d0 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
1e5e0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
1e5f0 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
1e600 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
1e610 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
1e620 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
1e630 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
1e640 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
1e650 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
1e660 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
1e670 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
1e680 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
1e690 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
1e6a0 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
1e6b0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
1e6c0 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
1e6d0 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
1e6e0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
1e6f0 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f  ive path. .** ^O
1e700 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
1e710 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
1e720 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
1e730 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
1e740 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
1e750 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a  (e.g. "C:")..**.
1e760 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
1e770 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
1e780 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
1e790 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
1e7a0 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
1e7b0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
1e7c0 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
1e7d0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
1e7e0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
1e7f0 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
1e800 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1e810 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  n]..** SQLite in
1e820 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c  terprets the fol
1e830 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65  lowing three que
1e840 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
1e850 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
1e860 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
1e870 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
1e880 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
1e890 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
1e8a0 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
1e8b0 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
1e8c0 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
1e8d0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1e8e0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
1e8f0 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
1e900 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
1e910 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1e920 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
1e930 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
1e940 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
1e950 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
1e960 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
1e970 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
1e980 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
1e990 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
1e9a0 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
1e9b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1e9c0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
1e9d0 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
1e9e0 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
1e9f0 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
1ea00 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
1ea10 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
1ea20 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
1ea30 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
1ea40 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
1ea50 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1ea60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1ea70 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
1ea80 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
1ea90 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
1eaa0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
1eab0 72 20 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a  r "ro", "rw" or.
1eac0 2a 2a 20 20 20 20 20 22 72 77 63 22 2e 20 41 74  **     "rwc". At
1ead0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
1eae0 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
1eaf0 76 61 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f  value is an erro
1eb00 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
1eb10 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
1eb20 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
1eb30 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1eb40 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
1eb50 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
1eb60 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
1eb70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1eb80 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
1eb90 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
1eba0 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
1ebb0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70  ent to sqlite3_p
1ebc0 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66  repare_v2(). ^If
1ebd0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
1ebe0 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
1ebf0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
1ec00 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1ec10 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
1ec20 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
1ec30 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
1ec40 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
1ec50 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1ec60 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
1ec70 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
1ec80 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
1ec90 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
1eca0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1ecb0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
1ecc0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
1ecd0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
1ece0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
1ecf0 41 54 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ATE. ^If sqlite3
1ed00 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a  _open_v2() is .*
1ed10 2a 20 20 20 20 20 75 73 65 64 2c 20 69 74 20 69  *     used, it i
1ed20 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
1ed30 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
1ed40 72 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  r the mode param
1ed50 65 74 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a  eter that is .**
1ed60 20 20 20 20 20 6c 65 73 73 20 72 65 73 74 72 69       less restri
1ed70 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
1ed80 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1ed90 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 61 73   flags passed as
1eda0 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20   the third .**  
1edb0 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a     parameter..**
1edc0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
1edd0 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
1ede0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
1edf0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
1ee00 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
1ee10 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
1ee20 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
1ee30 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
1ee40 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1ee50 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
1ee60 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1ee70 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
1ee80 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
1ee90 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
1eea0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1eeb0 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
1eec0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
1eed0 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
1eee0 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
1eef0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
1ef00 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
1ef10 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
1ef20 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
1ef30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1ef40 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
1ef50 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
1ef60 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
1ef70 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
1ef80 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
1ef90 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
1efa0 76 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20  viour requested 
1efb0 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
1efc0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
1efd0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
1efe0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1eff0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c  CACHE flag..** <
1f000 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
1f010 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
1f020 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
1f030 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1f040 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
1f050 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
1f060 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1f070 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1f080 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
1f090 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
1f0a0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
1f0b0 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
1f0c0 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
1f0d0 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
1f0e0 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
1f0f0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1f100 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
1f110 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1f120 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
1f130 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
1f140 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
1f150 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
1f160 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
1f170 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
1f180 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
1f190 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
1f1a0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1f1b0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
1f1c0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1f1d0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
1f1e0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
1f1f0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
1f200 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
1f210 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
1f220 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
1f230 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
1f240 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
1f250 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
1f260 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
1f270 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
1f280 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
1f290 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
1f2a0 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
1f2b0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
1f2c0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1f2d0 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
1f2e0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
1f2f0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1f300 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
1f310 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
1f320 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
1f330 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
1f340 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
1f350 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
1f360 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1f370 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
1f380 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
1f390 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
1f3a0 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
1f3b0 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
1f3c0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
1f3d0 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
1f3e0 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
1f3f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
1f400 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1f410 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
1f420 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
1f430 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
1f440 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
1f450 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
1f460 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
1f470 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
1f480 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
1f490 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
1f4a0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
1f4b0 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
1f4c0 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
1f4d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
1f4e0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1f4f0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1f500 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
1f510 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
1f520 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
1f530 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1f540 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
1f550 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
1f560 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
1f570 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
1f580 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
1f590 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1f5a0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
1f5b0 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e  ta.db?vfs=unix-n
1f5c0 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20  olock <td>.**   
1f5d0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
1f5e0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
1f5f0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
1f600 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
1f610 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72  -nolock"..** <tr
1f620 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1f630 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
1f640 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1f650 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
1f660 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
1f670 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
1f680 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
1f690 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
1f6a0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
1f6b0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1f6c0 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
1f6d0 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
1f6e0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
1f6f0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
1f700 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
1f710 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
1f720 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
1f730 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
1f740 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
1f750 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
1f760 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
1f770 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
1f780 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
1f790 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
1f7a0 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
1f7b0 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
1f7c0 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
1f7d0 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
1f7e0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
1f7f0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
1f800 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
1f810 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
1f820 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
1f830 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
1f840 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
1f850 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
1f860 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
1f870 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
1f880 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
1f890 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
1f8a0 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
1f8b0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
1f8c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
1f8d0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
1f8e0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
1f8f0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
1f900 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1f910 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
1f920 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1f930 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f940 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
1f950 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
1f960 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
1f970 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
1f980 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
1f990 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
1f9a0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
1f9b0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
1f9c0 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
1f9d0 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
1f9e0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
1f9f0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1fa00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
1fa10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1fa20 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1fa30 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1fa40 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1fa50 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1fa60 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1fa70 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1fa80 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1fa90 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1faa0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1fab0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1fac0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1fad0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1fae0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1faf0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1fb00 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1fb10 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1fb20 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1fb30 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1fb40 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1fb50 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1fb60 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1fb70 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1fb80 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1fb90 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1fba0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1fbb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1fbc0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1fbd0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1fbe0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1fbf0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1fc00 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1fc10 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
1fc20 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
1fc30 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
1fc40 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
1fc50 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
1fc60 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
1fc70 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
1fc80 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
1fc90 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
1fca0 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
1fcb0 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
1fcc0 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
1fcd0 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
1fce0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
1fcf0 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
1fd00 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
1fd10 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
1fd20 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
1fd30 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
1fd40 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
1fd50 64 20 6f 66 20 61 20 56 46 53 0a 2a 2a 20 69 6d  d of a VFS.** im
1fd60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  plementation and
1fd70 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
1fd80 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
1fd90 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
1fda0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
1fdb0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
1fdc0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
1fdd0 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
1fde0 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
1fdf0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1fe00 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
1fe10 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
1fe20 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
1fe30 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
1fe40 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
1fe50 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
1fe60 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
1fe70 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
1fe80 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
1fe90 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
1fea0 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
1feb0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
1fec0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
1fed0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
1fee0 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
1fef0 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
1ff00 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
1ff10 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
1ff20 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
1ff30 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
1ff40 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
1ff50 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   The value of P 
1ff60 69 73 20 74 72 75 65 20 69 66 20 69 74 20 69 73  is true if it is
1ff70 20 22 79 65 73 22 20 6f 72 20 22 74 72 75 65 22   "yes" or "true"
1ff80 20 6f 72 20 22 6f 6e 22 20 6f 72 20 0a 2a 2a 20   or "on" or .** 
1ff90 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
1ffa0 72 20 61 6e 64 20 69 73 20 66 61 6c 73 65 20 6f  r and is false o
1ffb0 74 68 65 72 77 69 73 65 2e 20 20 49 66 20 50 20  therwise.  If P 
1ffc0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 20 70  is not a query p
1ffd0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6f 6e 20 46  arameter.** on F
1ffe0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
1fff0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
20000 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
20010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
20020 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
20030 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
20040 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
20050 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
20060 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
20070 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
20080 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
20090 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
200a0 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
200b0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
200c0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
200d0 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
200e0 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
200f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
20100 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
20110 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
20120 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
20130 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
20140 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
20150 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
20160 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
20170 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
20180 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
20190 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
201a0 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
201b0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
201c0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
201d0 70 65 6e 20 56 46 53 20 6d 65 74 68 6f 64 2c 0a  pen VFS method,.
201e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
201f0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
20200 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
20210 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
20220 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63  ndesirable..*/.c
20230 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20240 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
20250 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
20260 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
20270 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
20280 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
20290 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
202a0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
202b0 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
202c0 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
202d0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
202e0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
202f0 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
20300 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
20310 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
20320 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
20330 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
20340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20350 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
20360 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
20370 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
20380 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
20390 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
203a0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
203b0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
203c0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
203d0 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
203e0 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
203f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
20400 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
20410 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
20420 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
20430 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
20440 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
20450 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
20460 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
20470 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
20480 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
20490 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
204a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
204b0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
204c0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
204d0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
204e0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
204f0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
20500 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
20510 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
20520 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
20530 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
20540 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
20550 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
20560 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
20570 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
20580 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
20590 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
205a0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
205b0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
205c0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
205d0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
205e0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
205f0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
20600 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
20610 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
20620 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
20630 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
20640 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
20650 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
20660 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
20670 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
20680 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
20690 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
206a0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
206b0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
206c0 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  )^.**.** When th
206d0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
206e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
206f0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
20700 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
20710 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
20720 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
20730 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
20740 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
20750 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
20760 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
20770 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
20780 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
20790 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
207a0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
207b0 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
207c0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
207d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
207e0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
207f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
20800 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
20810 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
20820 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
20830 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
20840 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
20850 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
20860 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
20870 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
20880 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
20890 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
208a0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
208b0 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
208c0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
208d0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
208e0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
208f0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
20900 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
20910 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
20920 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
20930 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
20940 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
20950 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
20960 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
20970 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
20980 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
20990 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
209a0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
209b0 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
209c0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
209d0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
209e0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
209f0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
20a00 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
20a10 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
20a20 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
20a30 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
20a40 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
20a50 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
20a60 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
20a70 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
20a80 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
20a90 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
20aa0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
20ab0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
20ac0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
20ad0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
20ae0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
20af0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
20b00 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
20b10 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
20b20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
20b30 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
20b40 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
20b50 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
20b60 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
20b70 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
20b80 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
20b90 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
20ba0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
20bb0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
20bc0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
20bd0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
20be0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
20bf0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
20c00 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
20c10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20c20 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
20c30 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
20c40 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
20c50 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
20c60 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
20c70 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
20c80 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
20c90 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
20ca0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
20cb0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
20cc0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
20cd0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
20ce0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
20cf0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
20d00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
20d10 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
20d20 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
20d30 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
20d40 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
20d50 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
20d60 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
20d70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20d80 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
20d90 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
20da0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
20db0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
20dc0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
20dd0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
20de0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
20df0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
20e00 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
20e10 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
20e20 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
20e30 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
20e40 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
20e50 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
20e60 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
20e70 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
20e80 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
20e90 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
20ea0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
20eb0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
20ec0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
20ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
20ee0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
20ef0 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
20f00 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
20f10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
20f20 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
20f30 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
20f40 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
20f50 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
20f60 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
20f70 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
20f80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
20f90 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
20fa0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
20fb0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
20fc0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
20fd0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
20fe0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
20ff0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
21000 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
21010 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
21020 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
21030 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
21040 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
21050 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
21060 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
21070 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
21080 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
21090 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
210a0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
210b0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
210c0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
210d0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
210e0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
210f0 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
21100 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
21110 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
21120 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
21130 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
21140 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
21150 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
21160 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
21170 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
21180 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
21190 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
211a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
211b0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
211c0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
211d0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
211e0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
211f0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
21200 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
21210 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
21220 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
21230 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
21240 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
21250 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
21260 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
21270 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
21280 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
21290 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
212a0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
212b0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
212c0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
212d0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
212e0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
212f0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
21300 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
21310 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
21320 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
21330 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
21340 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
21350 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
21360 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
21370 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
21380 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
21390 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
213a0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
213b0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
213c0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
213d0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
213e0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
213f0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
21400 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
21410 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
21420 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
21430 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
21440 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
21450 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
21460 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
21470 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
21480 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
21490 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
214a0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
214b0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
214c0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
214d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
214e0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
214f0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
21500 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
21510 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
21520 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
21530 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
21540 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
21550 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
21560 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
21570 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
21580 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
21590 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
215a0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
215b0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
215c0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
215d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
215e0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
215f0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
21600 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
21610 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
21620 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
21630 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
21640 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
21650 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
21660 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
21670 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
21680 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
21690 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
216a0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
216b0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
216c0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
216d0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
216e0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
216f0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
21700 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
21710 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
21720 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
21730 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
21740 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
21750 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
21760 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
21770 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
21780 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
21790 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
217a0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
217b0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
217c0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
217d0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
217e0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
217f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21800 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
21810 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
21820 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
21830 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
21840 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
21850 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
21860 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
21870 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
21880 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
21890 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
218a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
218b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
218c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
218d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
218e0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
218f0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
21900 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
21910 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
21920 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
21930 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
21940 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
21950 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
21960 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
21970 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21980 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
21990 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
219a0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
219b0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
219c0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
219d0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
219e0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
219f0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
21a00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
21a10 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
21a20 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
21a30 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
21a40 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
21a50 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
21a60 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
21a70 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
21a80 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
21a90 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
21aa0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
21ab0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
21ac0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
21ad0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21ae0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
21af0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
21b00 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
21b10 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
21b20 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
21b30 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
21b40 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
21b50 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
21b60 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
21b70 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
21b80 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
21b90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
21ba0 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
21bb0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
21bc0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
21bd0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
21be0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
21bf0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
21c00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21c10 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
21c20 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
21c30 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
21c40 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
21c50 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
21c60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
21c70 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
21c80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
21c90 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
21ca0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
21cb0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
21cc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
21cd0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
21ce0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
21cf0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
21d00 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
21d10 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
21d20 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
21d30 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
21d40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
21d50 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
21d60 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
21d70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
21d80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
21d90 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
21da0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
21db0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
21dc0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
21dd0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
21de0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
21df0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
21e00 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
21e10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21e20 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
21e30 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
21e40 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
21e50 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
21e60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
21e70 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
21e80 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
21e90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
21ea0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
21eb0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
21ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21ed0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
21ee0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
21ef0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
21f00 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
21f10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
21f20 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
21f30 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
21f40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
21f50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
21f60 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
21f70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
21f80 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
21f90 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
21fa0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
21fb0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
21fc0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
21fd0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
21fe0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
21ff0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
22000 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22010 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
22020 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
22030 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22040 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
22050 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
22060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22070 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
22080 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
22090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
220a0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
220b0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
220c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
220d0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
220e0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
220f0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
22100 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
22110 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
22120 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
22130 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
22140 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
22150 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
22160 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
22170 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
22180 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
22190 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
221a0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
221b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
221c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
221d0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
221e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
221f0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
22200 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
22210 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
22220 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
22230 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22240 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
22250 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
22260 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
22270 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
22280 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
22290 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
222a0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
222b0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
222c0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
222d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
222e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
222f0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
22300 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
22310 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
22320 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
22330 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22340 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
22350 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
22360 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
22370 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
22380 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
22390 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
223a0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
223b0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
223c0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
223d0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
223e0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
223f0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
22400 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
22410 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
22420 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
22430 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
22440 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
22450 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
22460 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
22470 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
22480 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
22490 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
224a0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
224b0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
224c0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
224d0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
224e0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
224f0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
22500 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
22510 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
22520 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
22530 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
22540 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
22550 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
22560 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
22570 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
22580 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
22590 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
225a0 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
225b0 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
225c0 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
225d0 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
225e0 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
225f0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
22600 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
22610 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
22620 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
22630 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
22640 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
22650 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
22660 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
22670 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
22680 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
22690 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
226a0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
226b0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
226c0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
226d0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
226e0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
226f0 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
22700 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
22710 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
22720 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22730 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
22740 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
22750 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
22760 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
22770 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
22780 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
22790 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
227a0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
227b0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
227c0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
227d0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
227e0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
227f0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
22800 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
22810 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
22820 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
22830 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
22840 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
22850 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
22860 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22870 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
22880 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
22890 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
228a0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
228b0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
228c0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
228d0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
228e0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
228f0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
22900 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
22910 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
22920 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
22930 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
22940 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
22950 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22960 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
22970 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
22980 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
22990 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
229a0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
229b0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
229c0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
229d0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
229e0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
229f0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
22a00 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
22a10 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
22a20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
22a30 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
22a40 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
22a50 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
22a60 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
22a70 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
22a80 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
22a90 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
22aa0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
22ab0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
22ac0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
22ad0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
22ae0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
22af0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
22b00 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
22b10 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
22b20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
22b30 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
22b40 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
22b50 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
22b60 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
22b70 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
22b80 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
22b90 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
22ba0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
22bb0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
22bc0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
22bd0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
22be0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22bf0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
22c00 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
22c10 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
22c20 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
22c30 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
22c40 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
22c50 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
22c60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22c70 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
22c80 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
22c90 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
22ca0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
22cb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
22cc0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
22cd0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
22ce0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
22cf0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
22d00 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
22d10 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
22d20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
22d30 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
22d40 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
22d50 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
22d60 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
22d70 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
22d80 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
22d90 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
22da0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
22db0 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
22dc0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
22dd0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
22de0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
22df0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
22e00 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
22e10 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
22e20 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
22e30 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
22e40 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
22e50 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
22e60 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
22e70 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
22e80 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
22e90 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
22ea0 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
22eb0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
22ec0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
22ed0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
22ee0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
22ef0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
22f00 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
22f10 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
22f20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
22f30 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
22f40 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
22f50 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
22f60 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
22f70 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
22f80 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
22f90 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
22fa0 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
22fb0 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
22fc0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
22fd0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
22fe0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
22ff0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
23000 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
23010 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
23020 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
23030 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a   the .** </li>.*
23040 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
23050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
23060 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
23070 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
23080 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
23090 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
230a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
230b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
230c0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
230d0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
230e0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
230f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
23100 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
23110 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
23120 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
23130 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
23140 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
23150 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
23160 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
23170 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
23180 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
23190 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
231a0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
231b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
231c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
231d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
231e0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
231f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
23200 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
23210 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
23220 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
23230 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
23240 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
23250 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
23260 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
23270 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
23280 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
23290 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
232a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
232b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
232c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
232d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
232e0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
232f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
23300 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
23310 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
23320 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
23330 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
23340 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
23350 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
23360 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
23370 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
23380 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
23390 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
233a0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
233b0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
233c0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
233d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
233e0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
233f0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
23400 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
23410 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
23420 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23430 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
23440 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
23450 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
23460 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
23470 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
23480 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
23490 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
234a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
234b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
234c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
234d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
234e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
234f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
23500 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
23510 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
23520 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
23530 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
23540 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
23550 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
23560 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23570 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
23580 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
23590 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
235a0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
235b0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
235c0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
235d0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
235e0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
235f0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
23600 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
23610 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
23620 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
23630 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
23640 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
23650 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
23660 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
23670 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23680 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
23690 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
236a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
236b0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
236c0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
236d0 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
236e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
236f0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
23700 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
23710 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
23720 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
23730 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
23740 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23750 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
23760 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
23770 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
23780 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23790 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
237a0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
237b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
237c0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
237d0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
237e0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
237f0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
23800 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
23810 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
23820 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
23830 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
23840 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
23850 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
23860 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
23870 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
23880 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
23890 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
238a0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
238b0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
238c0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
238d0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
238e0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
238f0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
23900 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
23910 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
23920 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
23930 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
23940 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
23950 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
23960 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
23970 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
23980 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
23990 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
239a0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
239b0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
239c0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
239d0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
239e0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
239f0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
23a00 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
23a10 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
23a20 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
23a30 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
23a40 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
23a50 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
23a60 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
23a70 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
23a80 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
23a90 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
23aa0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
23ab0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
23ac0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
23ad0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
23ae0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
23af0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
23b00 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
23b10 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
23b20 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
23b30 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
23b40 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
23b50 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
23b60 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
23b70 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
23b80 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
23b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
23ba0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
23bb0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
23bc0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
23bd0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
23be0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
23bf0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
23c00 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
23c10 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
23c20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23c30 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
23c40 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
23c50 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
23c60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23c70 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
23c80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23c90 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
23ca0 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
23cb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23cc0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
23cd0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
23ce0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
23cf0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
23d00 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
23d10 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
23d20 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
23d30 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
23d40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23d50 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
23d60 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
23d70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
23d80 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
23d90 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
23da0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
23db0 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
23dc0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
23dd0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
23de0 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
23df0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
23e00 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
23e10 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
23e20 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
23e30 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
23e40 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
23e50 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
23e60 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
23e70 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
23e80 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
23e90 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
23ea0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
23eb0 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
23ec0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
23ed0 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
23ee0 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
23ef0 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
23f00 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
23f10 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
23f20 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
23f30 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
23f40 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
23f50 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
23f60 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
23f70 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
23f80 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
23f90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
23fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23fb0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
23fc0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
23fd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
23fe0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23ff0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
24000 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24010 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
24020 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
24030 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
24040 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
24050 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
24060 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
24070 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
24080 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
24090 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
240a0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
240b0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
240c0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
240d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
240e0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
240f0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
24100 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
24110 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
24120 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
24130 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24140 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
24150 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
24160 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
24170 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
24180 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
24190 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
241a0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
241b0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
241c0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
241d0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
241e0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
241f0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
24200 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
24210 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
24220 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
24230 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
24240 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
24250 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
24260 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24270 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
24280 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
24290 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
242a0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
242b0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
242c0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
242d0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
242e0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
242f0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
24300 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
24310 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
24320 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
24330 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
24340 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
24350 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
24360 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
24370 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
24380 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
24390 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
243a0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
243b0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
243c0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
243d0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
243e0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
243f0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
24400 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
24410 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
24420 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
24430 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
24440 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
24450 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
24460 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
24470 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
24480 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
24490 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
244a0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
244b0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
244c0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
244d0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
244e0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
244f0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
24500 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
24510 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
24520 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
24530 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
24540 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
24550 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
24560 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
24570 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
24580 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
24590 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
245a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
245b0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
245c0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
245d0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
245e0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
245f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
24600 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
24610 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
24620 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
24630 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
24640 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
24650 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
24660 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
24670 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
24680 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24690 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
246a0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
246b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
246c0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
246d0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
246e0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
246f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
24700 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
24710 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
24720 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
24730 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
24740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
24750 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
24760 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
24770 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
24780 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
24790 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
247a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
247b0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
247c0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
247d0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
247e0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
247f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
24800 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
24810 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
24820 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
24830 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
24840 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
24850 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
24860 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
24870 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
24880 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
24890 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
248a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
248b0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
248c0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
248d0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
248e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
248f0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
24900 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
24910 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
24920 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
24930 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
24940 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
24950 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
24960 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
24970 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
24980 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
24990 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
249a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
249b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
249c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
249d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
249e0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
249f0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
24a00 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
24a10 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
24a20 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
24a30 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
24a40 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
24a50 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
24a60 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
24a70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
24a80 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
24a90 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
24aa0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
24ab0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
24ac0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24ad0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
24ae0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
24af0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
24b00 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
24b10 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
24b20 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
24b30 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
24b40 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
24b50 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
24b60 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
24b70 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
24b80 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
24b90 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
24ba0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
24bb0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
24bc0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
24bd0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
24be0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
24bf0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
24c00 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
24c10 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
24c20 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
24c30 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
24c40 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
24c50 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
24c60 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
24c70 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
24c80 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
24c90 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
24ca0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
24cb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
24cc0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
24cd0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
24ce0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
24cf0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
24d00 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
24d10 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
24d20 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
24d30 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
24d40 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
24d50 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
24d60 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
24d70 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
24d80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
24d90 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
24da0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
24db0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
24dc0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
24dd0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
24de0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
24df0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
24e00 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
24e10 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
24e20 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
24e30 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
24e40 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
24e50 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
24e60 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
24e70 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
24e80 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
24e90 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
24ea0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
24eb0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
24ec0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
24ed0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
24ee0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
24ef0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
24f00 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
24f10 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
24f20 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
24f30 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
24f40 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
24f50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
24f60 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
24f70 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
24f80 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
24f90 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
24fa0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
24fb0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
24fc0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
24fd0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
24fe0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
24ff0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
25000 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
25010 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
25020 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
25030 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
25040 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
25050 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
25060 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
25070 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
25080 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
25090 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
250a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
250b0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
250c0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
250d0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
250e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
250f0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
25100 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
25110 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ator..** If a no
25120 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
25130 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
25140 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
25150 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
25160 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
25170 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20  d_text16() then 
25180 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
25190 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
251a0 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
251b0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
251c0 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
251d0 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
251e0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
251f0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
25200 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
25210 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
25220 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
25230 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
25240 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
25250 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
25260 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
25270 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
25280 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
25290 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
252a0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
252b0 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
252c0 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
252d0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
252e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
252f0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
25300 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
25310 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
25320 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
25330 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
25340 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
25350 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
25360 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
25370 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
25380 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
25390 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
253a0 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
253b0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
253c0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
253d0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
253e0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
253f0 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  he call to sqlit
25400 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a  e3_bind_blob(),.
25410 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
25420 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74  text(), or sqlit
25430 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
25440 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66   fails.  .** ^If
25450 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
25460 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
25470 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
25480 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
25490 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
254a0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
254b0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
254c0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
254d0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
254e0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
254f0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
25500 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
25510 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
25520 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
25530 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
25540 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
25550 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
25560 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
25570 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
25580 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
25590 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
255a0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
255b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
255c0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
255d0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
255e0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
255f0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
25600 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
25610 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
25620 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
25630 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
25640 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
25650 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
25660 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
25670 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
25680 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
25690 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
256a0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
256b0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
256c0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
256d0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
256e0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
256f0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
25700 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
25710 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
25720 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
25730 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
25740 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
25750 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
25760 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
25770 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
25780 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
25790 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
257a0 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
257b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
257c0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
257d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
257e0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
257f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25800 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
25810 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
25820 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
25830 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
25840 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
25850 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
25860 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
25870 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
25880 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
25890 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
258a0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
258b0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
258c0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
258d0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
258e0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
258f0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
25900 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
25910 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
25920 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
25930 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
25940 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
25950 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
25960 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
25970 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
25980 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
25990 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
259a0 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
259b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
259c0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
259d0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
259e0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
259f0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
25a00 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
25a10 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
25a20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
25a30 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
25a40 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
25a50 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
25a60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25a70 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
25a80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
25a90 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
25aa0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
25ab0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25ac0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
25ad0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
25ae0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
25af0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
25b00 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
25b10 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
25b20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
25b30 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
25b40 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
25b50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25b60 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
25b70 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
25b80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25b90 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
25ba0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
25bb0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
25bc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
25bd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25be0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
25bf0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
25c00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
25c10 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
25c20 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
25c30 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
25c40 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
25c50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
25c60 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
25c70 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
25c80 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
25c90 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
25ca0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
25cb0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
25cc0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
25cd0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
25ce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
25cf0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
25d00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
25d10 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
25d20 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
25d30 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
25d40 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
25d50 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
25d60 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
25d70 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
25d80 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
25d90 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
25da0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
25db0 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
25dc0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
25dd0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
25de0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
25df0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
25e00 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
25e10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25e20 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
25e30 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
25e40 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
25e50 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
25e60 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
25e70 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
25e80 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
25e90 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
25ea0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
25eb0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
25ec0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
25ed0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
25ee0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
25ef0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
25f00 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
25f10 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
25f20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
25f30 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
25f40 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
25f50 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
25f60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25f70 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
25f80 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
25f90 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
25fa0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
25fb0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25fc0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
25fd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
25fe0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
25ff0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
26000 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26010 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
26020 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
26030 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26040 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
26050 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
26060 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
26070 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
26080 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
26090 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
260a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
260b0 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
260c0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
260d0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
260e0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
260f0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
26100 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
26110 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
26120 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
26130 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
26140 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
26150 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
26160 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
26170 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
26180 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
26190 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
261a0 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
261b0 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
261c0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
261d0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
261e0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
261f0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
26200 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
26210 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
26220 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
26230 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
26240 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
26250 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
26260 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
26270 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
26280 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
26290 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
262a0 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
262b0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
262c0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
262d0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
262e0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
262f0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
26300 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
26310 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
26320 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
26330 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
26340 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
26350 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26360 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
26370 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26380 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
26390 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
263a0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
263b0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
263c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
263d0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
263e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
263f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
26400 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
26410 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
26420 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
26430 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
26440 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
26450 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
26460 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
26470 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
26480 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
26490 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
264a0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
264b0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
264c0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
264d0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
264e0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
264f0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
26500 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
26510 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
26520 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
26530 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
26540 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
26550 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
26560 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
26570 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
26580 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
26590 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
265a0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
265b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
265c0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
265d0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
265e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
265f0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
26600 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
26610 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
26620 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
26630 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26640 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
26650 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26660 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26670 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
26680 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
26690 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
266a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
266b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
266c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
266d0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
266e0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
266f0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
26700 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
26710 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
26720 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
26730 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
26740 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
26750 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
26760 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
26770 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
26780 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
26790 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
267a0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
267b0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
267c0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
267d0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
267e0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
267f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
26800 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
26810 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
26820 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
26830 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
26840 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
26850 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
26860 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
26870 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26880 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
26890 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
268a0 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
268b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
268c0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
268d0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
268e0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
268f0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
26900 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
26910 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
26920 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26930 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
26940 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
26950 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
26960 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
26970 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
26980 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
26990 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
269a0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
269b0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
269c0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
269d0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
269e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
269f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
26a00 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
26a10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
26a20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
26a30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
26a40 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
26a50 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
26a60 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
26a70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
26a80 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
26a90 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
26aa0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
26ab0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
26ac0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26ad0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
26ae0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
26af0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
26b00 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
26b10 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
26b20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
26b30 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
26b40 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
26b50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
26b60 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
26b70 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
26b80 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
26b90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26ba0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
26bb0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
26bc0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
26bd0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
26be0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
26bf0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
26c00 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
26c10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26c20 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
26c30 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
26c40 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
26c50 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
26c60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26c70 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
26c80 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
26c90 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
26ca0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
26cb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
26cc0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
26cd0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
26ce0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
26cf0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
26d00 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
26d10 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
26d20 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
26d30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
26d40 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
26d50 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
26d60 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
26d70 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
26d80 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
26d90 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
26da0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
26db0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
26dc0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
26dd0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
26de0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
26df0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
26e00 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
26e10 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
26e20 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
26e30 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
26e40 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
26e50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
26e60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26e70 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
26e80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26e90 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
26ea0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
26eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26ec0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
26ed0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
26ee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
26ef0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
26f00 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
26f10 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
26f20 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
26f30 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
26f40 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
26f50 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
26f60 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
26f70 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
26f80 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
26f90 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
26fa0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
26fb0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
26fc0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
26fd0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
26fe0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
26ff0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
27000 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
27010 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
27020 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
27030 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
27040 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
27050 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
27060 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
27070 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
27080 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
27090 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
270a0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
270b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
270c0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
270d0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
270e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
270f0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
27100 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
27110 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
27120 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
27130 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
27140 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
27150 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
27160 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
27170 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
27180 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
27190 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
271a0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
271b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
271c0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
271d0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
271e0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
271f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
27200 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
27210 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
27220 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
27230 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
27240 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
27250 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
27260 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
27270 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
27280 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
27290 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
272a0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
272b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
272c0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
272d0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
272e0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
272f0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
27300 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
27310 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
27320 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
27330 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
27340 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
27350 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
27360 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
27370 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
27380 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
27390 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
273a0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
273b0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
273c0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
273d0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
273e0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
273f0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
27400 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
27410 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
27420 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
27430 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
27440 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
27450 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
27460 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
27470 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
27480 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
27490 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
274a0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
274b0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
274c0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
274d0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
274e0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
274f0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
27500 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
27510 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
27520 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
27530 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
27540 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
27550 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
27560 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
27570 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
27580 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
27590 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
275a0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
275b0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
275c0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
275d0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
275e0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
275f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
27600 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
27610 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
27620 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
27630 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
27640 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
27650 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
27660 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
27670 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
27680 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
27690 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
276a0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
276b0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
276c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
276d0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
276e0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
276f0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
27700 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
27710 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
27720 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
27730 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
27740 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
27750 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
27760 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27770 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
27780 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
27790 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
277a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
277b0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
277c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
277d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
277e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
277f0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
27800 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
27810 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
27820 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
27830 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
27840 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
27850 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27860 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
27870 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
27880 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27890 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
278a0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
278b0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
278c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
278d0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
278e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
278f0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
27900 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
27910 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
27920 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
27930 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
27940 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
27950 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
27960 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
27970 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
27980 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
27990 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
279a0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
279b0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
279c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
279d0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
279e0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
279f0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
27a00 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
27a10 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
27a20 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
27a30 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
27a40 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
27a50 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
27a60 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
27a70 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
27a80 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
27a90 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
27aa0 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
27ab0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
27ac0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
27ad0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
27ae0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
27af0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
27b00 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
27b10 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
27b20 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
27b30 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
27b40 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
27b50 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
27b60 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
27b70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
27b80 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
27b90 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
27ba0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
27bb0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
27bc0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
27bd0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
27be0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
27bf0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
27c00 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
27c10 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
27c20 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
27c30 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
27c40 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
27c50 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
27c60 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
27c70 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
27c80 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
27c90 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
27ca0 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
27cb0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
27cc0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
27cd0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
27ce0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
27cf0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
27d00 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
27d10 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
27d20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
27d30 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
27d40 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
27d50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
27d60 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
27d70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
27d80 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
27d90 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
27da0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
27db0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
27dc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27dd0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
27de0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
27df0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
27e00 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
27e10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27e20 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
27e30 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
27e40 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
27e50 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
27e60 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
27e70 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
27e80 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
27e90 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
27ea0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
27eb0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
27ec0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
27ed0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
27ee0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
27ef0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
27f00 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
27f10 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
27f20 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
27f30 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
27f40 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
27f50 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
27f60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27f70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
27f80 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
27f90 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
27fa0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
27fb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
27fc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
27fd0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
27fe0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
27ff0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
28000 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
28010 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
28020 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
28030 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
28040 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
28050 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
28060 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
28070 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
28080 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
28090 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
280a0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
280b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
280c0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
280d0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
280e0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
280f0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
28100 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
28110 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
28120 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
28130 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
28140 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
28150 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
28160 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
28170 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
28180 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
28190 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
281a0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
281b0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
281c0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
281d0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
281e0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
281f0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
28200 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
28210 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
28220 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
28230 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
28240 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
28250 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
28260 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
28270 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
28280 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
28290 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
282a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
282b0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
282c0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
282d0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
282e0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
282f0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
28300 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
28310 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
28320 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
28330 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
28340 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
28350 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
28360 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
28370 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
28380 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
28390 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
283a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
283b0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
283c0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
283d0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
283e0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
283f0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
28400 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
28410 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
28420 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
28430 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
28440 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
28450 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
28460 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
28470 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
28480 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
28490 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
284a0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
284b0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
284c0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
284d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
284e0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
284f0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
28500 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
28510 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
28520 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
28530 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
28540 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
28550 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
28560 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
28570 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
28580 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
28590 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
285a0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
285b0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
285c0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
285d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
285e0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
285f0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
28600 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
28610 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
28620 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
28630 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
28640 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
28650 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
28660 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
28670 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
28680 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
28690 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
286a0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
286b0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
286c0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
286d0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
286e0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
286f0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
28700 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
28710 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
28720 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
28730 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
28740 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
28750 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
28760 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
28770 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
28780 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
28790 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
287a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
287b0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
287c0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
287d0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
287e0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
287f0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
28800 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
28810 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
28820 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
28830 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
28840 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
28850 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
28860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
28870 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
28880 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
28890 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
288a0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
288b0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
288c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
288d0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
288e0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
288f0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
28900 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28910 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
28920 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
28930 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
28940 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
28950 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
28960 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
28970 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
28980 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
28990 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
289a0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
289b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
289c0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
289d0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
289e0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
289f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
28a00 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
28a10 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
28a20 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
28a30 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
28a40 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
28a50 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
28a60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
28a70 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
28a80 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
28a90 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
28aa0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
28ab0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
28ac0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
28ad0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
28ae0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
28af0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
28b00 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
28b10 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
28b20 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
28b30 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
28b40 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
28b50 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
28b60 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
28b70 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
28b80 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
28b90 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
28ba0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
28bb0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
28bc0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
28bd0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
28be0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
28bf0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
28c00 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
28c10 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
28c20 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
28c30 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
28c40 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
28c50 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
28c60 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
28c70 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
28c80 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
28c90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
28ca0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
28cb0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
28cc0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
28cd0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
28ce0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
28cf0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
28d00 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
28d10 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
28d20 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
28d30 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
28d40 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
28d50 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
28d60 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
28d70 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
28d80 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
28d90 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
28da0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
28db0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28dc0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
28dd0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
28de0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
28df0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
28e00 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
28e10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
28e20 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
28e30 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
28e40 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
28e50 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
28e60 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
28e70 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
28e80 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
28e90 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
28ea0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
28eb0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28ec0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
28ed0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
28ee0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
28ef0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
28f00 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
28f10 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
28f20 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
28f30 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
28f40 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
28f50 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
28f60 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
28f70 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
28f80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28f90 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
28fa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
28fb0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
28fc0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
28fd0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
28fe0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
28ff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
29000 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
29010 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
29020 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
29030 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29040 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
29050 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29060 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
29070 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
29080 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
29090 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
290a0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
290b0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
290c0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
290d0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
290e0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
290f0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
29100 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
29110 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29120 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
29130 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
29140 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
29150 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29160 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
29170 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
29180 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
29190 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
291a0 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
291b0 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
291c0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
291d0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
291e0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
291f0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
29200 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
29210 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
29220 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29230 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
29240 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
29250 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
29260 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
29270 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
29280 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
29290 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
292a0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
292b0 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
292c0 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
292d0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
292e0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
292f0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
29300 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
29310 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
29320 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
29330 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
29340 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
29350 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
29360 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
29370 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
29380 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
29390 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
293a0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
293b0 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
293c0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
293d0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
293e0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
293f0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
29400 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
29410 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
29420 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
29430 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
29440 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
29450 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
29460 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
29470 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
29480 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
29490 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
294a0 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
294b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
294c0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
294d0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
294e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
294f0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
29500 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
29510 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
29520 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
29530 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
29540 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
29550 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
29560 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
29570 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
29580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29590 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
295a0 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
295b0 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
295c0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
295d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
295e0 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
295f0 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74  "result set" int
29600 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  erface..**.** ^T
29610 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
29620 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
29630 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
29640 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
29650 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
29660 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
29670 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
29680 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
29690 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
296a0 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
296b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
296c0 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
296d0 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
296e0 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
296f0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
29700 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
29710 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
29720 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
29730 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
29740 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
29750 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
29760 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
29770 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
29780 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
29790 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
297a0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
297b0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
297c0 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
297d0 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
297e0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
297f0 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
29800 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
29810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
29820 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
29830 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
29840 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
29850 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
29860 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
29870 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
29880 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
29890 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
298a0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
298b0 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
298c0 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
298d0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
298e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
298f0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
29900 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
29910 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
29920 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
29930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
29940 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
29950 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
29960 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
29970 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
29980 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
29990 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
299a0 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
299b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
299c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
299d0 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
299e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
299f0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
29a00 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
29a10 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
29a20 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
29a30 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
29a40 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
29a50 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
29a60 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
29a70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29a80 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
29a90 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
29aa0 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
29ab0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
29ac0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
29ad0 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
29ae0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
29af0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
29b00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29b10 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
29b20 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
29b30 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
29b40 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
29b50 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
29b60 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
29b70 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
29b80 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
29b90 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
29ba0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
29bb0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
29bc0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
29bd0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
29be0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
29bf0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
29c00 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
29c10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29c20 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
29c30 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
29c40 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
29c50 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
29c60 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
29c70 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
29c80 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
29c90 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
29ca0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
29cb0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
29cc0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
29cd0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
29ce0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
29cf0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
29d00 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
29d10 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
29d20 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
29d30 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
29d40 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
29d50 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
29d60 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
29d70 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
29d80 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
29d90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
29da0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29db0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
29dc0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
29dd0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
29de0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
29df0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
29e00 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
29e10 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
29e20 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
29e30 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
29e40 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
29e50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
29e60 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
29e70 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
29e80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29e90 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
29ea0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
29eb0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
29ec0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
29ed0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
29ee0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
29ef0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
29f00 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
29f10 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
29f20 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
29f30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
29f40 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
29f50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
29f60 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
29f70 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
29f80 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
29f90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29fa0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
29fb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
29fc0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
29fd0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
29fe0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
29ff0 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
2a000 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2a010 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2a020 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2a030 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2a040 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
2a050 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2a060 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2a070 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2a080 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2a090 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2a0a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
2a0b0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2a0c0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2a0d0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2a0e0 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
2a0f0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2a100 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2a110 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2a120 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2a130 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2a140 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2a150 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
2a160 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2a170 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
2a180 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2a190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a1a0 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
2a1b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a1c0 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
2a1d0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
2a1e0 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
2a1f0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
2a200 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
2a210 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
2a220 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
2a230 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a240 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
2a250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a260 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
2a270 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
2a280 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
2a290 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
2a2a0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2a2b0 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
2a2c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2a2d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2a2e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
2a2f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
2a300 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
2a310 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
2a320 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2a330 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
2a340 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2a350 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2a360 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2a370 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
2a380 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2a390 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  ** ^The object r
2a3a0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2a3b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2a3c0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
2a3d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a3e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
2a3f0 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
2a400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a410 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
2a420 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
2a430 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2a440 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2a450 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2a460 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
2a470 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2a480 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a490 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2a4a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a4b0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
2a4c0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
2a4d0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
2a4e0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
2a4f0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2a500 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
2a510 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2a520 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2a530 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2a540 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
2a550 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2a560 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
2a570 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
2a580 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
2a590 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
2a5a0 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
2a5b0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2a5c0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2a5d0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2a5e0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2a5f0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2a600 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2a610 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2a620 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2a630 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2a640 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2a650 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
2a660 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
2a670 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
2a680 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
2a690 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
2a6a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2a6b0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2a6c0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2a6d0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
2a6e0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
2a6f0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
2a700 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
2a710 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2a720 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
2a730 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
2a740 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
2a750 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2a760 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
2a770 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
2a780 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2a790 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2a7a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2a7b0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2a7c0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2a7d0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2a7e0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2a7f0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2a800 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2a810 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2a820 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2a830 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2a840 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2a850 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2a860 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2a870 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2a880 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2a890 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2a8a0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2a8b0 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2a8c0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2a8d0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2a8e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2a8f0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2a900 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
2a910 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2a920 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2a930 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2a940 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2a950 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2a960 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2a970 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2a980 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
2a990 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
2a9a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
2a9b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
2a9c0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2a9d0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2a9e0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2a9f0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
2aa00 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2aa10 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2aa20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
2aa30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2aa40 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2aa50 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2aa60 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2aa70 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2aa80 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2aa90 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2aaa0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
2aab0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
2aac0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2aad0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2aae0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2aaf0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2ab00 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2ab10 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2ab20 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2ab30 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2ab40 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2ab50 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2ab60 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2ab70 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2ab80 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2ab90 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2aba0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2abb0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2abc0 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2abd0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2abe0 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2abf0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2ac00 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2ac10 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2ac20 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2ac30 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2ac40 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2ac50 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2ac60 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2ac70 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2ac80 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2ac90 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2aca0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2acb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2acc0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2acd0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2ace0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2acf0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2ad00 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2ad10 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2ad20 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2ad30 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2ad40 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2ad50 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2ad60 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2ad70 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2ad80 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2ad90 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2ada0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2adb0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2adc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2add0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2ade0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2adf0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2ae00 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2ae10 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2ae20 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2ae30 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2ae40 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2ae50 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2ae60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2ae70 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2ae80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2ae90 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2aea0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2aeb0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2aec0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2aed0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2aee0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2aef0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2af00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2af10 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2af20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2af30 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2af40 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2af50 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2af60 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2af70 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2af80 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2af90 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2afa0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2afb0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2afc0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2afd0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2afe0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2aff0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2b000 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2b010 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2b020 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2b030 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2b040 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2b050 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2b060 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2b070 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2b080 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2b090 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2b0a0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2b0b0 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2b0c0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2b0d0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2b0e0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2b0f0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2b100 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2b110 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2b120 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2b130 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2b140 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2b150 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2b160 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2b170 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2b180 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2b190 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2b1a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2b1b0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2b1c0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2b1d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2b1e0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2b1f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2b200 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2b210 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b220 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2b230 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2b240 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2b250 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2b260 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2b270 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2b280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b290 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2b2a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2b2b0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2b2c0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2b2d0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2b2e0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2b2f0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2b300 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2b310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b320 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2b330 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b340 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2b350 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2b360 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2b370 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2b380 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2b390 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2b3a0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2b3b0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2b3c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2b3d0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2b3e0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2b3f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b400 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2b410 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2b420 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2b430 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2b440 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2b450 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2b460 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2b470 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2b480 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2b490 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2b4a0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2b4b0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2b4c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b4d0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2b4e0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2b4f0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2b500 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2b510 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2b520 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2b530 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2b540 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2b550 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
2b560 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2b570 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
2b580 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
2b590 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
2b5a0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2b5b0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
2b5c0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2b5d0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2b5e0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2b5f0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2b600 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2b610 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2b620 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2b630 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2b640 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2b650 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2b660 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2b670 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2b680 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2b690 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2b6a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2b6b0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2b6c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2b6d0 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
2b6e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2b6f0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2b700 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2b710 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2b720 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2b730 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2b740 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2b750 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2b760 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b770 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
2b780 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b790 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2b7a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2b7b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2b7c0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2b7d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2b7e0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2b7f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2b800 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2b810 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2b820 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2b830 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2b840 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
2b850 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2b860 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2b870 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b880 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2b890 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2b8a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2b8b0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2b8c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2b8d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2b8e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2b8f0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2b900 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2b910 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2b920 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2b930 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2b940 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
2b950 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b960 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2b970 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2b980 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b990 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
2b9a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2b9b0 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
2b9c0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
2b9d0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
2b9e0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
2b9f0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
2ba00 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
2ba10 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
2ba20 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
2ba30 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
2ba40 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2ba50 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2ba60 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
2ba70 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
2ba80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2ba90 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
2baa0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2bab0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
2bac0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2bad0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2bae0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2baf0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2bb00 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2bb10 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2bb20 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2bb30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bb40 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2bb50 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2bb60 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2bb70 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2bb80 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2bb90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2bba0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2bbb0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2bbc0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2bbd0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2bbe0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2bbf0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2bc00 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2bc10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2bc20 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2bc30 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2bc40 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2bc50 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2bc60 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2bc70 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2bc80 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2bc90 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2bca0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2bcb0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2bcc0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2bcd0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2bce0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2bcf0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2bd00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bd10 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2bd20 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2bd30 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2bd40 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2bd50 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2bd60 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2bd70 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2bd80 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2bd90 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2bda0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2bdb0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2bdc0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
2bdd0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2bde0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2bdf0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2be00 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2be10 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2be20 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2be30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2be40 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2be50 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2be60 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2be70 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2be80 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2be90 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2bea0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2beb0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
2bec0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2bed0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2bee0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2bef0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2bf00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2bf10 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2bf20 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2bf30 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2bf40 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2bf50 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2bf60 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2bf70 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2bf80 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2bf90 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2bfa0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
2bfb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bfc0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
2bfd0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2bfe0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2bff0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2c000 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2c010 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2c020 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2c030 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c040 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2c050 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2c060 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
2c070 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2c080 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2c090 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2c0a0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
2c0b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c0c0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2c0d0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
2c0e0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2c0f0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2c100 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2c110 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2c120 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2c130 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2c140 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
2c150 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2c160 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2c170 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2c180 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
2c190 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2c1a0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2c1b0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2c1c0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
2c1d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2c1e0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2c1f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c200 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
2c210 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
2c220 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2c230 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2c240 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
2c250 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
2c260 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
2c270 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2c280 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2c290 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2c2a0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2c2b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c2c0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2c2d0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2c2e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c2f0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
2c300 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
2c310 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
2c320 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
2c330 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
2c340 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
2c350 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
2c360 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
2c370 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
2c380 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
2c390 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2c3a0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2c3b0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
2c3c0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
2c3d0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
2c3e0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
2c3f0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
2c400 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
2c410 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2c420 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
2c430 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
2c440 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
2c450 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
2c460 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
2c470 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
2c480 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
2c490 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2c4a0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2c4b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2c4c0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
2c4d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2c4e0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
2c4f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
2c500 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
2c510 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2c520 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
2c530 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
2c540 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
2c550 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c560 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2c570 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
2c580 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
2c590 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
2c5a0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2c5b0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2c5c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2c5d0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2c5e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2c5f0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2c600 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
2c610 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2c620 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2c630 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
2c640 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
2c650 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
2c660 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
2c670 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
2c680 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
2c690 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
2c6a0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
2c6b0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
2c6c0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
2c6d0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
2c6e0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
2c6f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
2c700 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
2c710 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
2c720 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
2c730 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
2c740 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
2c750 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
2c760 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2c770 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2c780 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2c790 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2c7a0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
2c7b0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
2c7c0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
2c7d0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2c7e0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2c7f0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2c800 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
2c810 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
2c820 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
2c830 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2c840 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2c850 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
2c860 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
2c870 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
2c880 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
2c890 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
2c8a0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
2c8b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2c8c0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
2c8d0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2c8e0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2c8f0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2c900 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2c910 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2c920 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2c930 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2c940 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66  rs.  Every SQL f
2c950 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2c960 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61  tation must be a
2c970 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2c980 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2c990 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2c9a0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2c9b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2c9c0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2c9d0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2c9e0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2c9f0 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63  her.  ^An applic
2ca00 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
2ca10 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2ca20 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2ca30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ca40 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2ca50 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2ca60 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2ca70 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2ca80 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2ca90 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2caa0 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
2cab0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2cac0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2cad0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
2cae0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
2caf0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
2cb00 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
2cb10 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2cb20 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
2cb30 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
2cb40 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
2cb50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2cb60 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
2cb70 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
2cb80 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
2cb90 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2cba0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2cbb0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
2cbc0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
2cbd0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
2cbe0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
2cbf0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
2cc00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2cc10 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
2cc20 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
2cc30 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
2cc40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
2cc50 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
2cc60 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
2cc70 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
2cc80 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
2cc90 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
2cca0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
2ccb0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
2ccc0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
2ccd0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2cce0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2ccf0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
2cd00 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
2cd10 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2cd20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2cd30 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
2cd40 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
2cd50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
2cd60 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2cd70 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2cd80 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2cd90 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
2cda0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2cdb0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2cdc0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
2cdd0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
2cde0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
2cdf0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
2ce00 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
2ce10 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2ce20 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2ce30 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2ce40 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
2ce50 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
2ce60 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
2ce70 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
2ce80 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
2ce90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2cea0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ceb0 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
2cec0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
2ced0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
2cee0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2cef0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2cf00 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
2cf10 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
2cf20 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
2cf30 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
2cf40 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
2cf50 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
2cf60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2cf70 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
2cf80 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
2cf90 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
2cfa0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
2cfb0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2cfc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2cfd0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
2cfe0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
2cff0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
2d000 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
2d010 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
2d020 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
2d030 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
2d040 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
2d050 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
2d060 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
2d070 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
2d080 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
2d090 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2d0a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d0b0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
2d0c0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2d0d0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
2d0e0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2d0f0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
2d100 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
2d110 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
2d120 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
2d130 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
2d140 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
2d150 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
2d160 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2d170 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
2d180 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
2d190 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d1a0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
2d1b0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
2d1c0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
2d1d0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
2d1e0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
2d1f0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2d200 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
2d210 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
2d220 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
2d230 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
2d240 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
2d250 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
2d260 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
2d270 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
2d280 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
2d290 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2d2a0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
2d2b0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
2d2c0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
2d2d0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
2d2e0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2d2f0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
2d300 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
2d310 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2d320 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2d330 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
2d340 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
2d350 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
2d360 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
2d370 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2d380 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2d390 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
2d3a0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
2d3b0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
2d3c0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
2d3d0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
2d3e0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
2d3f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d400 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
2d410 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2d420 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2d430 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
2d440 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
2d450 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2d460 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
2d470 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
2d480 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
2d490 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d4a0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
2d4b0 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
2d4c0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2d4d0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
2d4e0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2d4f0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
2d500 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d510 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
2d520 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2d530 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2d540 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2d550 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2d560 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2d570 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2d580 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2d590 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2d5a0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2d5b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d5c0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2d5d0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2d5e0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2d5f0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
2d600 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2d610 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
2d620 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2d630 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
2d640 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2d650 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2d660 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2d670 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2d680 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2d690 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2d6a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2d6b0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2d6c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2d6d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2d6e0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2d6f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2d700 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
2d710 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d720 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
2d730 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2d740 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2d750 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2d760 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2d770 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2d780 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2d790 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2d7a0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2d7b0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2d7c0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2d7d0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2d7e0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2d7f0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2d800 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
2d810 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
2d820 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
2d830 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2d840 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
2d850 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
2d860 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
2d870 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
2d880 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
2d890 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
2d8a0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
2d8b0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
2d8c0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
2d8d0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2d8e0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
2d8f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2d900 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
2d910 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2d920 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
2d930 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
2d940 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
2d950 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
2d960 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
2d970 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
2d980 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d990 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
2d9a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2d9b0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
2d9c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2d9d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
2d9e0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
2d9f0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
2da00 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
2da10 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
2da20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2da30 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
2da40 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
2da50 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
2da60 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2da70 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
2da80 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
2da90 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
2daa0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2dab0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
2dac0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
2dad0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
2dae0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
2daf0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
2db00 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
2db10 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
2db20 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
2db30 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
2db40 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
2db50 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
2db60 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
2db70 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
2db80 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
2db90 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2dba0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
2dbb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2dbc0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2dbd0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2dbe0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
2dbf0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2dc00 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2dc10 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
2dc20 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2dc30 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
2dc40 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
2dc50 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2dc60 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
2dc70 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
2dc80 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
2dc90 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
2dca0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
2dcb0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2dcc0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2dcd0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2dce0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2dcf0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2dd00 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2dd10 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
2dd20 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2dd30 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
2dd40 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
2dd50 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
2dd60 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
2dd70 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
2dd80 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2dd90 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
2dda0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
2ddb0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
2ddc0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
2ddd0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
2dde0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
2ddf0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
2de00 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
2de10 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
2de20 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
2de30 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
2de40 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
2de50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2de60 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2de70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2de80 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2de90 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
2dea0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
2deb0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2dec0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2ded0 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
2dee0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
2def0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
2df00 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2df10 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
2df20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2df30 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
2df40 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
2df50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2df60 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
2df70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
2df80 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
2df90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2dfa0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
2dfb0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
2dfc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2dfd0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
2dfe0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2dff0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
2e000 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2e010 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e020 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
2e030 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
2e040 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
2e050 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e060 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
2e070 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
2e080 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
2e090 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
2e0a0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
2e0b0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
2e0c0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
2e0d0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2e0e0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
2e0f0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
2e100 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
2e110 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2e120 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e130 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
2e140 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
2e150 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
2e160 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
2e170 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
2e180 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e190 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2e1a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
2e1b0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
2e1c0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
2e1d0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
2e1e0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
2e1f0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
2e200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e210 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
2e220 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e230 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
2e240 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
2e250 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
2e260 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
2e270 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
2e280 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
2e290 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
2e2a0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2e2b0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2e2c0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
2e2d0 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
2e2e0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
2e2f0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
2e300 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
2e310 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
2e320 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
2e330 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
2e340 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
2e350 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
2e360 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
2e370 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
2e380 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
2e390 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
2e3a0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
2e3b0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
2e3c0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
2e3d0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
2e3e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2e3f0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
2e400 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
2e410 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
2e420 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
2e430 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
2e440 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
2e450 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
2e460 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2e470 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2e480 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2e490 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2e4a0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2e4b0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
2e4c0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2e4d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2e4e0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2e4f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2e500 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
2e510 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
2e520 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2e530 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2e540 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
2e550 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
2e560 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2e570 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2e580 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e590 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
2e5a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2e5b0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2e5c0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2e5d0 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
2e5e0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
2e5f0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
2e600 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
2e610 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
2e620 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2e630 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
2e640 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2e650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2e660 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
2e670 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2e680 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2e690 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2e6a0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2e6b0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
2e6c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2e6d0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2e6e0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2e6f0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
2e700 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
2e710 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
2e720 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
2e730 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2e740 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2e750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2e760 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2e770 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e780 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2e790 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2e7a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2e7b0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
2e7c0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2e7d0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2e7e0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2e7f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2e800 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2e810 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2e820 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2e830 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2e840 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2e850 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e860 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
2e870 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
2e880 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
2e890 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
2e8a0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2e8b0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
2e8c0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
2e8d0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
2e8e0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
2e8f0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
2e900 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
2e910 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2e920 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
2e930 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2e940 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
2e950 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
2e960 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
2e970 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
2e980 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
2e990 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
2e9a0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
2e9b0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2e9c0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
2e9d0 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
2e9e0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2e9f0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
2ea00 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2ea10 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
2ea20 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2ea30 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
2ea40 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
2ea50 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
2ea60 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2ea70 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
2ea80 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
2ea90 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
2eaa0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
2eab0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
2eac0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
2ead0 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
2eae0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2eaf0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
2eb00 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
2eb10 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
2eb20 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
2eb30 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
2eb40 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
2eb50 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
2eb60 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
2eb70 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
2eb80 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
2eb90 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
2eba0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
2ebb0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
2ebc0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
2ebd0 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
2ebe0 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
2ebf0 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
2ec00 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
2ec10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ec20 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2ec30 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
2ec40 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2ec50 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
2ec60 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
2ec70 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
2ec80 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2ec90 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
2eca0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
2ecb0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
2ecc0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
2ecd0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2ece0 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
2ecf0 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
2ed00 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
2ed10 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
2ed20 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
2ed30 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
2ed40 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
2ed50 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
2ed60 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2ed70 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
2ed80 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2ed90 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
2eda0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
2edb0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
2edc0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
2edd0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
2ede0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2edf0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
2ee00 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
2ee10 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2ee20 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
2ee30 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
2ee40 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
2ee50 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2ee60 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2ee70 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2ee80 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2ee90 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
2eea0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
2eeb0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
2eec0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
2eed0 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
2eee0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2eef0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
2ef00 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
2ef10 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
2ef20 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2ef30 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2ef40 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2ef50 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2ef60 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
2ef70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2ef80 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2ef90 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2efa0 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
2efb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2efc0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
2efd0 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
2efe0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
2eff0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2f000 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2f010 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f020 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2f030 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
2f040 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
2f050 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
2f060 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
2f070 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
2f080 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f090 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
2f0a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f0b0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
2f0c0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
2f0d0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
2f0e0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
2f0f0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
2f100 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2f110 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2f120 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2f130 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2f140 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
2f150 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f160 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2f170 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2f180 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2f190 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f1a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f1b0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2f1c0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
2f1d0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2f1e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2f1f0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
2f200 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f210 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2f220 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2f230 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f240 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
2f250 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2f260 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2f270 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2f280 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2f290 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2f2a0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2f2b0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2f2c0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2f2d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2f2e0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
2f2f0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
2f300 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2f310 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2f320 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2f330 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
2f340 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
2f350 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2f360 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2f370 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2f380 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2f390 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2f3a0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
2f3b0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
2f3c0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
2f3d0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
2f3e0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
2f3f0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2f400 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
2f410 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
2f420 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
2f430 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
2f440 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
2f450 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
2f460 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2f470 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2f480 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2f490 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2f4a0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2f4b0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2f4c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2f4d0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2f4e0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2f4f0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2f500 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2f510 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2f520 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
2f530 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
2f540 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2f550 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
2f560 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
2f570 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2f580 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
2f590 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
2f5a0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2f5b0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
2f5c0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
2f5d0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
2f5e0 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
2f5f0 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
2f600 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
2f610 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ocation..**.** ^
2f620 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2f630 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
2f640 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2f650 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
2f660 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
2f670 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
2f680 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2f690 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
2f6a0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
2f6b0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
2f6c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f6d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
2f6e0 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
2f6f0 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
2f700 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
2f710 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
2f720 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
2f730 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
2f740 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
2f750 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
2f760 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
2f770 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
2f780 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
2f790 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2f7a0 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
2f7b0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2f7c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
2f7d0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
2f7e0 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
2f7f0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
2f800 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
2f810 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
2f820 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
2f830 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
2f840 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
2f850 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f860 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
2f870 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2f880 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
2f890 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
2f8a0 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
2f8b0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
2f8c0 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
2f8d0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f  .** ^If it is no
2f8e0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
2f8f0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
2f900 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
2f910 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
2f920 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2f930 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
2f940 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
2f950 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
2f960 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
2f970 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
2f980 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
2f990 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
2f9a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2f9b0 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
2f9c0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
2f9d0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
2f9e0 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
2f9f0 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
2fa00 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
2fa10 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
2fa20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
2fa30 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54  at any time.  ^T
2fa40 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
2fa50 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
2fa60 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
2fa70 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
2fa80 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
2fa90 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
2faa0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
2fab0 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
2fac0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
2fad0 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
2fae0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
2faf0 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
2fb00 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
2fb10 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
2fb20 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
2fb30 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
2fb40 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs].)^.**.** The
2fb50 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2fb60 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2fb70 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2fb80 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2fb90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2fba0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
2fbb0 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
2fbc0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
2fbd0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
2fbe0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
2fbf0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2fc00 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2fc10 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
2fc20 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
2fc30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
2fc40 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
2fc50 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
2fc60 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
2fc70 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
2fc80 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
2fc90 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
2fca0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
2fcb0 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
2fcc0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
2fcd0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2fce0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2fcf0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
2fd00 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
2fd10 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
2fd20 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
2fd30 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
2fd40 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
2fd50 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
2fd60 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
2fd70 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2fd80 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
2fd90 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
2fda0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
2fdb0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
2fdc0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
2fdd0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
2fde0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
2fdf0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
2fe00 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
2fe10 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2fe20 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
2fe30 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
2fe40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
2fe50 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
2fe60 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
2fe70 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
2fe80 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
2fe90 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
2fea0 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
2feb0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
2fec0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2fed0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
2fee0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
2fef0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
2ff00 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2ff10 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
2ff20 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
2ff30 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
2ff40 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
2ff50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ff60 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
2ff70 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
2ff80 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
2ff90 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2ffa0 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
2ffb0 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
2ffc0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
2ffd0 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
2ffe0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2fff0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
30000 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30010 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
30020 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30030 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
30040 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
30050 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
30060 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
30070 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
30080 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
30090 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
300a0 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
300b0 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
300c0 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
300d0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
300e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
300f0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
30100 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
30110 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
30120 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
30130 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
30140 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30150 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
30160 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30170 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
30180 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
30190 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
301a0 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
301b0 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
301c0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
301d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
301e0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
301f0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
30200 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
30210 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
30220 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
30230 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
30240 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
30250 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
30260 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
30270 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30280 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
30290 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
302a0 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
302b0 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
302c0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
302d0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
302e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
302f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
30300 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
30310 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
30320 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
30330 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
30340 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30350 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
30360 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
30370 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
30380 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
30390 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
303a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
303b0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
303c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
303d0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
303e0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
303f0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
30400 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
30410 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
30420 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
30430 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
30440 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
30450 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
30460 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30470 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
30480 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
30490 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
304a0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
304b0 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
304c0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
304d0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
304e0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
304f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
30500 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
30510 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
30520 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
30530 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30540 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
30550 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
30560 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
30570 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
30580 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30590 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
305a0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
305b0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
305c0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
305d0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
305e0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
305f0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
30600 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
30610 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
30620 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
30630 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
30640 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30650 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
30660 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30670 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
30680 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
30690 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
306a0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
306b0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
306c0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
306d0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
306e0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
306f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30700 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
30710 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30720 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
30730 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
30740 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
30750 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
30760 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
30770 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
30780 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
30790 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
307a0 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
307b0 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
307c0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
307d0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
307e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
307f0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
30800 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
30810 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
30820 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
30830 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
30840 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
30850 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
30860 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
30870 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
30880 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
30890 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
308a0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
308b0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
308c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
308d0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
308e0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
308f0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
30900 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30910 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
30920 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
30930 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
30940 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
30950 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
30960 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
30970 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
30980 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
30990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
309a0 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
309b0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
309c0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
309d0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
309e0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
309f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
30a00 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
30a10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
30a20 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
30a30 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
30a40 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
30a50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30a60 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30a70 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
30a80 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
30a90 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
30aa0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
30ab0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30ac0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
30ad0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
30ae0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
30af0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
30b00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30b10 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
30b20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
30b30 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
30b40 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
30b50 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
30b60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
30b70 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
30b80 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
30b90 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
30ba0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30bb0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30bc0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
30bd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30be0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
30bf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30c00 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
30c10 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
30c20 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
30c30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30c40 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
30c50 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
30c60 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
30c70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30c80 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30c90 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
30ca0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
30cb0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
30cc0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
30cd0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
30ce0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
30cf0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
30d00 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
30d10 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
30d20 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
30d30 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
30d40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
30d50 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
30d60 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
30d70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30d80 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
30d90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
30da0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
30db0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30dc0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
30dd0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
30de0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
30df0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
30e00 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
30e10 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
30e20 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
30e30 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
30e40 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
30e50 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
30e60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
30e70 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
30e80 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
30e90 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
30ea0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
30eb0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
30ec0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
30ed0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
30ee0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
30ef0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30f00 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
30f10 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
30f20 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
30f30 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
30f40 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
30f50 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
30f60 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
30f70 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
30f80 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
30f90 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
30fa0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
30fb0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
30fc0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
30fd0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
30fe0 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
30ff0 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
31000 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
31010 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
31020 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
31030 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
31040 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
31050 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
31060 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
31070 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
31080 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
31090 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
310a0 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
310b0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
310c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
310d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
310e0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
310f0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
31100 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
31110 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
31120 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
31130 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
31140 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
31150 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
31160 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
31170 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
31180 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
31190 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
311a0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
311b0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
311c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
311d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
311e0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
311f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
31200 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
31210 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
31220 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
31230 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
31240 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
31250 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
31260 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
31270 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
31280 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
31290 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
312a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
312b0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
312c0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
312d0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
312e0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
312f0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
31300 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
31310 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
31320 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31330 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
31340 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31350 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
31360 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
31370 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
31380 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
31390 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
313a0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
313b0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
313c0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
313d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
313e0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
313f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31400 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
31410 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31420 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
31430 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31440 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31450 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
31460 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
31470 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31480 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
31490 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
314a0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
314b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
314c0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
314d0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
314e0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
314f0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
31500 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
31510 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
31520 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
31530 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
31540 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
31550 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
31560 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
31570 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
31580 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
31590 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
315a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
315b0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
315c0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
315d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
315e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
315f0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
31600 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
31610 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
31620 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
31630 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
31640 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
31650 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
31660 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
31670 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
31680 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
31690 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
316a0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
316b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
316c0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
316d0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
316e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
316f0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
31700 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
31710 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
31720 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
31730 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31740 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
31750 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
31760 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
31770 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
31780 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31790 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
317a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
317b0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
317c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
317d0 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
317e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
317f0 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
31800 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
31810 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
31820 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31830 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
31840 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
31850 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31860 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
31870 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31880 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31890 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
318a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
318b0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
318c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
318d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
318e0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
318f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
31900 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
31910 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
31920 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
31930 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
31940 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
31950 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31960 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
31970 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
31980 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
31990 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
319a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
319b0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
319c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
319d0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
319e0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
319f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31a00 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
31a10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
31a20 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
31a30 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
31a40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31a50 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
31a60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
31a70 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
31a80 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
31a90 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31aa0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
31ab0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
31ac0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
31ad0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31ae0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
31af0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
31b00 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
31b10 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
31b20 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
31b30 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
31b40 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
31b50 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
31b60 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
31b70 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
31b80 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
31b90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
31ba0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
31bb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
31bc0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
31bd0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
31be0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
31bf0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
31c00 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31c10 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
31c20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31c30 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
31c40 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
31c50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
31c60 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
31c70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
31c80 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
31c90 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
31ca0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
31cb0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
31cc0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
31cd0 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
31ce0 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
31cf0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
31d00 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
31d10 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
31d20 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
31d30 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
31d40 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
31d50 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
31d60 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
31d70 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
31d80 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
31d90 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
31da0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
31db0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
31dc0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
31dd0 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
31de0 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
31df0 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
31e00 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
31e10 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
31e20 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
31e30 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
31e40 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
31e50 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
31e60 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
31e70 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
31e80 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
31e90 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
31ea0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
31eb0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
31ec0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
31ed0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
31ee0 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
31ef0 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
31f00 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
31f10 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
31f20 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
31f30 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
31f40 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
31f50 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
31f60 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
31f70 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
31f80 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
31f90 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
31fa0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
31fb0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
31fc0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
31fd0 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
31fe0 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
31ff0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
32000 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
32010 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
32020 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
32030 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
32040 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
32050 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
32060 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
32070 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
32080 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
32090 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
320a0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
320b0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
320c0 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
320d0 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
320e0 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
320f0 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
32100 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
32110 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
32120 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
32130 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
32140 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
32150 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
32160 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
32170 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
32180 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
32190 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
321a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
321b0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
321c0 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
321d0 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
321e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
321f0 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
32200 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
32210 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
32220 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
32230 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
32240 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
32250 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
32260 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
32270 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
32280 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
32290 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
322a0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
322b0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
322c0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
322d0 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
322e0 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
322f0 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
32300 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
32310 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
32320 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
32330 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
32340 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
32350 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
32360 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
32370 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
32380 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
32390 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
323a0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
323b0 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
323c0 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
323d0 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
323e0 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
323f0 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
32400 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
32410 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
32420 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
32430 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
32440 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
32450 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
32460 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
32470 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
32480 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
32490 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
324a0 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
324b0 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
324c0 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
324d0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
324e0 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
324f0 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
32500 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
32510 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
32520 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
32530 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
32540 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
32550 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
32560 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
32570 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
32580 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
32590 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
325a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
325b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
325c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
325d0 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
325e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
325f0 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
32600 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
32610 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
32620 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
32630 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
32640 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
32650 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
32660 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
32670 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
32680 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
32690 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
326a0 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
326b0 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
326c0 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
326d0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
326e0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
326f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32700 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
32710 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
32720 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
32730 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
32740 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
32750 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
32760 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32770 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
32780 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
32790 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
327a0 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
327b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
327c0 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
327d0 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
327e0 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
327f0 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
32800 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
32810 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
32820 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32830 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
32840 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
32850 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
32860 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
32870 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
32880 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
32890 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
328a0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
328b0 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
328c0 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
328d0 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
328e0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
328f0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
32900 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
32910 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
32920 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
32930 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
32940 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
32950 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
32960 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
32970 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32980 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32990 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
329a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
329b0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
329c0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
329d0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
329e0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
329f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
32a00 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
32a10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32a20 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32a30 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
32a40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
32a50 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
32a60 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
32a70 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
32a80 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
32a90 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
32aa0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
32ab0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
32ac0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
32ad0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32ae0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
32af0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
32b00 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
32b10 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
32b20 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
32b30 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
32b40 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
32b50 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
32b60 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
32b70 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
32b80 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
32b90 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
32ba0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
32bb0 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
32bc0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
32bd0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
32be0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
32bf0 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
32c00 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
32c10 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
32c20 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
32c30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
32c40 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
32c50 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
32c60 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
32c70 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
32c80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
32c90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
32ca0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
32cb0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
32cc0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
32cd0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
32ce0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
32cf0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
32d00 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
32d10 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
32d20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
32d30 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
32d40 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
32d50 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
32d60 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
32d70 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
32d80 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
32d90 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
32da0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
32db0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
32dc0 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
32dd0 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
32de0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
32df0 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
32e00 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
32e10 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
32e20 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
32e30 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
32e40 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
32e50 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
32e60 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
32e70 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
32e80 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
32e90 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
32ea0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
32eb0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
32ec0 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
32ed0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
32ee0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
32ef0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
32f00 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
32f10 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
32f20 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
32f30 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
32f40 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
32f50 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
32f60 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
32f70 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
32f80 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
32f90 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
32fa0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
32fb0 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
32fc0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
32fd0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
32fe0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
32ff0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
33000 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
33010 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
33020 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
33030 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
33040 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
33050 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33060 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
33070 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
33080 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
33090 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
330a0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
330b0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
330c0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
330d0 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
330e0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
330f0 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
33100 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
33110 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
33120 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
33130 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
33140 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  .);..#ifdef SQLI
33150 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a  TE_HAS_CODEC./*.
33160 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
33170 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
33180 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
33190 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
331a0 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
331b0 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
331c0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
331d0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
331e0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
331f0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
33200 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
33210 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
33220 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
33230 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
33240 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
33250 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
33260 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
33270 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
33280 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
33290 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
332a0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
332b0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
332c0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
332d0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
332e0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
332f0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
33300 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
33310 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
33320 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
33330 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
33340 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
33350 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
33360 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
33370 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
33380 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
33390 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
333a0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
333b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
333c0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
333d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
333e0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
333f0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
33400 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
33410 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
33420 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
33430 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
33440 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
33450 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
33460 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
33470 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
33480 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
33490 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
334a0 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
334b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
334c0 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
334d0 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
334e0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
334f0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
33500 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
33510 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
33520 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
33530 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
33540 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
33550 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
33560 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
33570 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
33580 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
33590 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
335a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
335b0 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
335c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
335d0 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
335e0 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
335f0 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
33600 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33610 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
33620 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
33630 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
33640 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
33650 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
33660 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
33670 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
33680 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
33690 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
336a0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
336b0 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
336c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
336d0 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
336e0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
336f0 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
33700 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
33710 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
33720 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
33730 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
33740 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
33750 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
33760 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
33770 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
33780 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
33790 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
337a0 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
337b0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
337c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
337d0 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
337e0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
337f0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
33800 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
33810 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
33820 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
33830 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
33840 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
33850 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
33860 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
33870 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
33880 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
33890 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
338a0 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
338b0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
338c0 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
338d0 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
338e0 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
338f0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
33900 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73  graphs..*/.int s
33910 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
33920 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33930 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
33940 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
33950 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
33960 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
33970 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
33980 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
33990 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
339a0 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
339b0 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
339c0 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
339d0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
339e0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
339f0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
33a00 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
33a10 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
33a20 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
33a30 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
33a40 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
33a50 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
33a60 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
33a70 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
33a80 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
33a90 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
33aa0 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
33ab0 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
33ac0 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
33ad0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
33ae0 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
33af0 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
33b00 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
33b10 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
33b20 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
33b30 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
33b40 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
33b50 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
33b60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33b70 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
33b80 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
33b90 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
33ba0 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
33bb0 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
33bc0 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
33bd0 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
33be0 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
33bf0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
33c00 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
33c10 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
33c20 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
33c30 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
33c40 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
33c50 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
33c60 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
33c70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
33c80 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
33c90 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
33ca0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
33cb0 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
33cc0 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
33cd0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
33ce0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
33cf0 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
33d00 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
33d10 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
33d20 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
33d30 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
33d40 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
33d50 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
33d60 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
33d70 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
33d80 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
33d90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
33da0 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
33db0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
33dc0 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
33dd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
33de0 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
33df0 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
33e00 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
33e10 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
33e20 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
33e30 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
33e40 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
33e50 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
33e60 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
33e70 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
33e80 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
33e90 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
33ea0 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
33eb0 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
33ec0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
33ed0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
33ee0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
33ef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
33f00 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
33f10 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f  it Mode.** KEYWO
33f20 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
33f30 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68   mode}.**.** ^Th
33f40 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
33f50 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
33f60 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
33f70 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
33f80 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
33f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33fa0 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
33fb0 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
33fc0 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
33fd0 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ly.  ^Autocommit
33fe0 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
33ff0 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f  efault..** ^Auto
34000 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
34010 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
34020 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
34030 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
34040 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
34050 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
34060 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
34070 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
34080 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
34090 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
340a0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
340b0 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
340c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
340d0 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
340e0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
340f0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
34100 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
34110 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
34120 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
34130 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
34140 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
34150 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
34160 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
34170 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
34180 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
34190 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
341a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
341b0 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
341c0 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
341d0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
341e0 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
341f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
34200 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
34210 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
34220 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
34230 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
34240 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
34250 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
34260 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
34270 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
34280 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
34290 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
342a0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
342b0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
342c0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
342d0 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
342e0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
342f0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
34300 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
34310 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
34320 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
34330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34340 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
34350 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
34360 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
34370 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74  ongs.  ^The [dat
34380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34390 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
343a0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
343b0 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
343c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
343d0 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  ion].** that was
343e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
343f0 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
34400 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
34410 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
34420 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
34430 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
34440 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
34450 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
34460 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
34470 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
34480 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
34490 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
344a0 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
344b0 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20  he Filename For 
344c0 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
344d0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
344e0 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65   sqlite3_db_file
344f0 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66  name(D,N) interf
34500 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
34510 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e  inter to a filen
34520 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ame.** associate
34530 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20  d with database 
34540 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  N of connection 
34550 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61  D.  ^The main da
34560 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68  tabase file.** h
34570 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69  as the name "mai
34580 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  n".  If there is
34590 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61 74   no attached dat
345a0 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64  abase N on the d
345b0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
345c0 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64  ction D, or if d
345d0 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20 74  atabase N is a t
345e0 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d  emporary or in-m
345f0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20  emory database, 
34600 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  then.** a NULL p
34610 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
34620 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
34630 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64  ilename returned
34640 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
34650 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74 20  n is the output 
34660 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50  of the.** xFullP
34670 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f  athname method o
34680 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49  f the [VFS].  ^I
34690 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
346a0 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
346b0 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75  ill be an absolu
346c0 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65  te pathname, eve
346d0 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  n if the filenam
346e0 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65  e used.** to ope
346f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  n the database o
34700 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20  riginally was a 
34710 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20  URI or relative 
34720 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e  pathname..*/.con
34730 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
34740 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c  _db_filename(sql
34750 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20  ite3 *db, const 
34760 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a  char *zDbName);.
34770 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34780 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
34790 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
347a0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
347b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
347c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
347d0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
347e0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
347f0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
34800 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
34810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34820 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
34830 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
34840 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
34850 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
34860 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
34870 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
34880 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
34890 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
348a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
348b0 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
348c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
348d0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
348e0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
348f0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
34900 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
34910 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
34920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
34930 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
34940 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
34950 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
34960 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
34970 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
34980 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
34990 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
349a0 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
349b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
349c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
349d0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
349e0 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
349f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
34a00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34a10 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
34a20 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
34a30 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
34a40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34a50 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
34a60 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
34a70 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
34a80 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
34a90 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
34aa0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
34ab0 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
34ac0 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
34ad0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
34ae0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
34af0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
34b00 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
34b10 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
34b20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34b30 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
34b40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
34b50 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
34b60 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
34b70 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
34b80 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
34b90 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
34ba0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
34bb0 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
34bc0 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
34bd0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
34be0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
34bf0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
34c00 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
34c10 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
34c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34c30 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
34c40 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
34c50 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
34c60 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
34c70 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
34c80 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
34c90 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
34ca0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
34cb0 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
34cc0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
34cd0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
34ce0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
34cf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
34d00 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
34d10 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
34d20 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
34d30 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
34d40 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
34d50 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
34d60 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
34d70 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
34d80 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
34d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34da0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
34db0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
34dc0 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
34dd0 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
34de0 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61  .** The commit a
34df0 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  nd rollback hook
34e00 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e   callbacks are n
34e10 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a  ot reentrant..**
34e20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
34e30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
34e40 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
34e50 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
34e60 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
34e70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
34e80 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
34e90 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
34ea0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
34eb0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
34ec0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
34ed0 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
34ee0 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
34ef0 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
34f00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
34f10 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
34f20 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
34f30 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
34f40 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
34f50 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
34f60 20 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e   that running an
34f70 79 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74  y other SQL stat
34f80 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e  ements, includin
34f90 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  g SELECT stateme
34fa0 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c  nts,.** or merel
34fb0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
34fc0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
34fd0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
34fe0 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66  ep()] will modif
34ff0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
35000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
35010 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
35020 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
35030 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
35040 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20  ** ^Registering 
35050 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
35060 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
35070 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  lback..**.** ^Wh
35080 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
35090 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
350a0 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
350b0 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
350c0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
350d0 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
350e0 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49  ue normally.  ^I
350f0 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  f the commit hoo
35100 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e  k.** returns non
35110 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
35120 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76  [COMMIT] is conv
35130 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f  erted into a [RO
35140 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65  LLBACK]..** ^The
35150 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
35160 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72  s invoked on a r
35170 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73  ollback that res
35180 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d  ults from a comm
35190 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72  it.** hook retur
351a0 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a  ning non-zero, j
351b0 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20  ust as it would 
351c0 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65  be with any othe
351d0 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  r rollback..**.*
351e0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
351f0 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
35200 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
35210 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
35220 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
35230 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
35240 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
35250 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
35260 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
35270 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
35280 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
35290 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
352a0 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72  occur..** ^The r
352b0 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
352c0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
352d0 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
352e0 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
352f0 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
35300 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
35310 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35320 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
35330 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
35340 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
35350 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
35360 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
35370 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
35380 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
35390 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
353a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
353b0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
353c0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
353d0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
353e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
353f0 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
35400 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
35410 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
35420 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
35430 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
35440 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
35450 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
35460 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
35470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
35480 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
35490 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
354a0 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
354b0 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
354c0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
354d0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
354e0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
354f0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
35500 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
35510 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  function.** for 
35520 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
35530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
35540 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
35550 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
35560 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
35570 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
35580 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
35590 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75  en a.** row is u
355a0 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
355b0 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
355c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
355d0 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ent to the callb
355e0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
355f0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
35600 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
35610 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e  3_update_hook().
35620 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
35630 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  callback argumen
35640 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
35650 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
35660 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a  LITE_DELETE],.**
35670 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
35680 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  TE], depending o
35690 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
356a0 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
356b0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62  callback.** to b
356c0 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  e invoked..** ^T
356d0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
356e0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
356f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
35700 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
35710 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
35720 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65  e and table name
35730 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
35740 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
35750 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c   ^The final call
35760 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
35770 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
35780 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e   the row..** ^In
35790 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
357a0 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
357b0 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65  the [rowid] afte
357c0 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  r the update tak
357d0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
357e0 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  ^(The update hoo
357f0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
35800 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
35810 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65  ystem tables are
35820 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e  .** modified (i.
35830 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  e. sqlite_master
35840 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
35850 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ence).)^.**.** ^
35860 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  In the current i
35870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74  mplementation, t
35880 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
35890 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  * is not invoked
358a0 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f   when duplicatio
358b0 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
358c0 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e  ed because of an
358d0 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54  .** [ON CONFLICT
358e0 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52   | ON CONFLICT R
358f0 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20  EPLACE] clause. 
35900 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64   ^Nor is the upd
35910 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f  ate hook.** invo
35920 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72  ked when rows ar
35930 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  e deleted using 
35940 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  the [truncate op
35950 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  timization]..** 
35960 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64  The exceptions d
35970 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70  efined in this p
35980 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63  aragraph might c
35990 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
359a0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
359b0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
359c0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d  e update hook im
359d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
359e0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
359f0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
35a00 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
35a10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
35a20 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75  at invoked the u
35a30 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79  pdate hook.  Any
35a40 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
35a50 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
35a60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
35a70 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
35a80 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
35a90 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
35aa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
35ab0 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
35ac0 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64  riggered the upd
35ad0 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74  ate hook..** Not
35ae0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
35af0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
35b00 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
35b10 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
35b20 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
35b30 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
35b40 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
35b50 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
35b60 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
35b70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
35b80 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50  pdate_hook(D,C,P
35b90 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65  ) function.** re
35ba0 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75  turns the P argu
35bb0 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
35bc0 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f  evious call.** o
35bd0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
35be0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35bf0 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
35c00 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
35c10 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65  l on D..**.** Se
35c20 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
35c30 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
35c40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
35c50 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
35c60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  .** interfaces..
35c70 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
35c80 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
35c90 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
35ca0 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
35cb0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
35cc0 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
35cd0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
35ce0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
35cf0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
35d00 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
35d10 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b  Pager Cache.** K
35d20 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
35d30 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28   cache}.**.** ^(
35d40 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
35d50 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
35d60 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
35d70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
35d80 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
35d90 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
35da0 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61   between [databa
35db0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20  se connection | 
35dc0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20  connections].** 
35dd0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
35de0 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73  base. Sharing is
35df0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
35e00 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
35e10 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64  .** and disabled
35e20 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
35e30 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a   is false.)^.**.
35e40 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e  ** ^Cache sharin
35e50 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
35e60 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
35e70 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
35e80 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
35e90 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
35ea0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
35eb0 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
35ec0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
35ed0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
35ee0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
35ef0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
35f00 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
35f10 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73  ** ^(The cache s
35f20 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
35f30 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
35f40 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
35f50 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
35f60 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
35f70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
35f80 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
35f90 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
35fa0 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
35fb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35fc0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
35fd0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
35fe0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
35ff0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
36000 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
36010 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  pened.)^.**.** ^
36020 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  (This routine re
36030 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
36040 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
36050 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
36060 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63   disabled.** suc
36070 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
36080 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
36090 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
360a0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72  e.)^.**.** ^Shar
360b0 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
360c0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
360d0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
360e0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
360f0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
36100 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
36110 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
36120 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
36130 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
36140 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
36150 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  icitly..**.** Se
36160 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65  e Also:  [SQLite
36170 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f   Shared-Cache Mo
36180 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  de].*/.int sqlit
36190 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
361a0 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
361b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74  .** CAPI3REF: At
361c0 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
361d0 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20  ap Memory.**.** 
361e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
361f0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
36200 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
36210 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73   to free N bytes
36220 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  .** of heap memo
36230 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
36240 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
36250 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
36260 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74  ons.** held by t
36270 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
36280 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73  ary.   Memory us
36290 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
362a0 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
362b0 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
362c0 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
362d0 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
362e0 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ial memory..** ^
362f0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
36300 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
36310 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
36320 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
36330 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
36340 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
36350 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
36360 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
36370 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36380 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
36390 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d  routine is a no-
363a0 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72  op returning zer
363b0 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  o.** if SQLite i
363c0 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77  s not compiled w
363d0 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  ith [SQLITE_ENAB
363e0 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
363f0 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  MENT]..**.** See
36400 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
36410 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  db_release_memor
36420 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  y()].*/.int sqli
36430 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
36440 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
36450 43 41 50 49 33 52 45 46 3a 20 46 72 65 65 20 4d  CAPI3REF: Free M
36460 65 6d 6f 72 79 20 55 73 65 64 20 42 79 20 41 20  emory Used By A 
36470 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
36480 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
36490 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73  qlite3_db_releas
364a0 65 5f 6d 65 6d 6f 72 79 28 44 29 20 69 6e 74 65  e_memory(D) inte
364b0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
364c0 6f 20 66 72 65 65 20 61 73 20 6d 75 63 68 20 68  o free as much h
364d0 65 61 70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 73  eap.** memory as
364e0 20 70 6f 73 73 69 62 6c 65 20 66 72 6f 6d 20 64   possible from d
364f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36500 6f 6e 20 44 2e 20 55 6e 6c 69 6b 65 20 74 68 65  on D. Unlike the
36510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
36520 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
36530 6e 74 65 72 66 61 63 65 2c 20 74 68 69 73 20 69  nterface, this i
36540 6e 74 65 72 66 61 63 65 20 69 73 20 65 66 66 65  nterface is effe
36550 63 74 20 65 76 65 6e 0a 2a 2a 20 77 68 65 6e 20  ct even.** when 
36560 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 45 4e 41  then [SQLITE_ENA
36570 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
36580 45 4d 45 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  EMENT] compile-t
36590 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ime option is.**
365a0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
365b0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
365c0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
365d0 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  y()].*/.int sqli
365e0 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d  te3_db_release_m
365f0 65 6d 6f 72 79 28 73 71 6c 69 74 65 33 2a 29 3b  emory(sqlite3*);
36600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36610 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74  : Impose A Limit
36620 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a   On Heap Size.**
36630 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36640 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
36650 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
36660 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69  ets and/or queri
36670 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c  es the.** soft l
36680 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
36690 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
366a0 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
366b0 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
366c0 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74  e..** ^SQLite st
366d0 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65  rives to keep he
366e0 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a  ap memory utiliz
366f0 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20  ation below the 
36700 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d  soft heap.** lim
36710 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20 74  it by reducing t
36720 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
36730 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70  es held in the p
36740 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20  age cache.** as 
36750 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67  heap memory usag
36760 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74 68  es approaches th
36770 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
36780 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
36790 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61 75   is "soft" becau
367a0 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53  se even though S
367b0 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
367c0 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74   stay.** below t
367d0 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c  he limit, it wil
367e0 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d  l exceed the lim
367f0 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20 67  it rather than g
36800 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53  enerate.** an [S
36810 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72  QLITE_NOMEM] err
36820 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  or.  In other wo
36830 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65  rds, the soft he
36840 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20  ap limit .** is 
36850 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
36860 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
36870 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
36880 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
36890 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20 73  mit64() is the s
368a0 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f  ize of.** the so
368b0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72  ft heap limit pr
368c0 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2c  ior to the call,
368d0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 69 6e 20   or negative in 
368e0 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 0a 2a  the case of an.*
368f0 2a 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  * error.  ^If th
36900 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20  e argument N is 
36910 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e  negative.** then
36920 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61   no change is ma
36930 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68  de to the soft h
36940 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63  eap limit.  Henc
36950 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  e, the current.*
36960 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f  * size of the so
36970 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
36980 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
36990 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  by invoking.** s
369a0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
369b0 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68 20  _limit64() with 
369c0 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d  a negative argum
369d0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ent..**.** ^If t
369e0 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
369f0 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73   zero then the s
36a00 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
36a10 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
36a20 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61  * ^(The soft hea
36a30 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65  p limit is not e
36a40 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63  nforced in the c
36a50 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
36a60 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20  ation.** if one 
36a70 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f  or more of follo
36a80 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20  wing conditions 
36a90 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20  are true:.**.** 
36aa0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
36ab0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
36ac0 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e   is set to zero.
36ad0 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20  .** <li> Memory 
36ae0 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69  accounting is di
36af0 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63  sabled using a c
36b00 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68  ombination of th
36b10 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  e.**      [sqlit
36b20 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
36b30 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
36b40 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d  TUS],...) start-
36b50 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a  time option and.
36b60 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c  **      the [SQL
36b70 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
36b80 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74  TATUS] compile-t
36b90 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
36ba0 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69  li> An alternati
36bb0 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ve page cache im
36bc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
36bd0 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a  specified using.
36be0 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
36bf0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
36c00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
36c10 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  ,...)..** <li> T
36c20 68 65 20 70 61 67 65 20 63 61 63 68 65 20 61 6c  he page cache al
36c30 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73  locates from its
36c40 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c   own memory pool
36c50 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20   supplied.**    
36c60 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f    by [sqlite3_co
36c70 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
36c80 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c  NFIG_PAGECACHE],
36c90 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e  ...) rather than
36ca0 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68  .**      from th
36cb0 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e  e heap..** </ul>
36cc0 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69  )^.**.** Beginni
36cd0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
36ce0 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68  ersion 3.7.3, th
36cf0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
36d00 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a  t is enforced.**
36d10 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
36d20 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
36d30 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
36d40 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
36d50 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  NT].** compile-t
36d60 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ime option is in
36d70 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51  voked.  With [SQ
36d80 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
36d90 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a  RY_MANAGEMENT],.
36da0 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ** the soft heap
36db0 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63   limit is enforc
36dc0 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f  ed on every memo
36dd0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20  ry allocation.  
36de0 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49  Without.** [SQLI
36df0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
36e00 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68  _MANAGEMENT], th
36e10 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
36e20 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63  t is only enforc
36e30 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72  ed.** when memor
36e40 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62  y is allocated b
36e50 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  y the page cache
36e60 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67 67 65  .  Testing sugge
36e70 73 74 73 20 74 68 61 74 20 62 65 63 61 75 73 65  sts that because
36e80 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61 63  .** the page cac
36e90 68 65 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d  he is the predom
36ea0 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65  inate memory use
36eb0 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73  r in SQLite, mos
36ec0 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
36ed0 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61  s will achieve a
36ee0 64 65 71 75 61 74 65 20 73 6f 66 74 20 68 65 61  dequate soft hea
36ef0 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d  p limit enforcem
36f00 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74  ent without.** t
36f10 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54  he use of [SQLIT
36f20 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
36f30 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a  MANAGEMENT]..**.
36f40 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74 61  ** The circumsta
36f50 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69 63 68  nces under which
36f60 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66   SQLite will enf
36f70 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20 68 65  orce the soft he
36f80 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20  ap limit may.** 
36f90 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72  changes in futur
36fa0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
36fb0 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  Lite..*/.sqlite3
36fc0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73  _int64 sqlite3_s
36fd0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
36fe0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e  (sqlite3_int64 N
36ff0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37000 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53  EF: Deprecated S
37010 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49  oft Heap Limit I
37020 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52  nterface.** DEPR
37030 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69  ECATED.**.** Thi
37040 73 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65  s is a deprecate
37050 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
37060 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
37070 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
37080 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  * interface.  Th
37090 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72  is routine is pr
370a0 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f  ovided for histo
370b0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
370c0 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c  ity.** only.  Al
370d0 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  l new applicatio
370e0 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  ns should use th
370f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f  e.** [sqlite3_so
37100 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
37110 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74  )] interface rat
37120 68 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e  her than this on
37130 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
37140 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
37150 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37160 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f  imit(int N);.../
37170 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
37180 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
37190 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
371a0 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  f A Table.**.** 
371b0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
371c0 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61  turns metadata a
371d0 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20  bout a specific 
371e0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63  column of a spec
371f0 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65  ific.** database
37200 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c   table accessibl
37210 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74  e using the [dat
37220 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37230 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73  ] handle.** pass
37240 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
37250 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
37260 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  t..**.** ^The co
37270 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69  lumn is identifi
37280 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
37290 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  , third and four
372a0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
372b0 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
372c0 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  n. ^The second p
372d0 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
372e0 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
372f0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
37300 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
37310 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63  mp", or an attac
37320 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
37330 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
37340 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
37350 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20  or NULL. ^If it 
37360 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
37370 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
37380 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
37390 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
373a0 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
373b0 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64  e algorithm used
373c0 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
373d0 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65   engine to.** re
373e0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
373f0 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
37400 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  es..**.** ^The t
37410 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
37420 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
37430 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
37440 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
37450 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  lumn.** name of 
37460 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
37470 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
37480 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
37490 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  se parameters.**
374a0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
374b0 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73  .** ^Metadata is
374c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
374d0 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
374e0 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
374f0 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a  sed as the 5th.*
37500 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  * and subsequent
37510 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
37520 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41  his function. ^A
37530 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75  ny of these argu
37540 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20  ments may be.** 
37550 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
37560 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ase the correspo
37570 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66  nding element of
37580 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69   metadata is omi
37590 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62  tted..**.** ^(<b
375a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
375b0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
375c0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72  .** <tr><th> Par
375d0 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70  ameter <th> Outp
375e0 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ut<br>Type <th> 
375f0 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a   Description.**.
37600 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20  ** <tr><td> 5th 
37610 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
37620 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a   <td> Data type.
37630 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20  ** <tr><td> 6th 
37640 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
37650 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65   <td> Name of de
37660 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
37670 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e  sequence.** <tr>
37680 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e  <td> 7th <td> in
37690 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
376a0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61  rue if column ha
376b0 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
376c0 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c  straint.** <tr><
376d0 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74  td> 8th <td> int
376e0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
376f0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
37700 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
37710 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c  ARY KEY.** <tr><
37720 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74  td> 9th <td> int
37730 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
37740 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
37750 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a  [AUTOINCREMENT].
37760 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
37770 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
37780 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
37790 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
377a0 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69  he character poi
377b0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66  nters returned f
377c0 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72  or the.** declar
377d0 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63  ation type and c
377e0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
377f0 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20  e is valid only 
37800 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a  until the next.*
37810 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51  * call to any SQ
37820 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  Lite API functio
37830 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
37840 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
37850 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
37860 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  iew, an [error c
37870 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
37880 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
37890 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e  specified column
378a0 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69   is "rowid", "oi
378b0 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  d" or "_rowid_" 
378c0 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47  and an.** [INTEG
378d0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
378e0 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20  column has been 
378f0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
37900 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  red, then the ou
37910 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
37920 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74  rs are set for t
37930 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  he explicitly de
37940 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e  clared column. ^
37950 28 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a  (If there is no.
37960 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  ** explicitly de
37970 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20  clared [INTEGER 
37980 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c  PRIMARY KEY] col
37990 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
379a0 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
379b0 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f  rs are set as fo
379c0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  llows:.**.** <pr
379d0 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74  e>.**     data t
379e0 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a  ype: "INTEGER".*
379f0 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20  *     collation 
37a00 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52  sequence: "BINAR
37a10 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75  Y".**     not nu
37a20 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69  ll: 0.**     pri
37a30 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20  mary key: 1.**  
37a40 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e     auto incremen
37a50 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e  t: 0.** </pre>)^
37a60 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
37a70 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
37a80 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
37a90 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
37aa0 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
37ab0 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
37ac0 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
37ad0 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
37ae0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
37af0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
37b00 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b  t be found, an [
37b10 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
37b20 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
37b30 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66  rror message lef
37b40 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74  t.** in the [dat
37b50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37b60 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  ] (to be retriev
37b70 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
37b80 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a  _errmsg()).)^.**
37b90 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73  .** ^This API is
37ba0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
37bb0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
37bc0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
37bd0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
37be0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
37bf0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
37c00 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
37c10 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
37c20 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75  lite3_table_colu
37c30 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73  mn_metadata(.  s
37c40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
37c50 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
37c60 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
37c70 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
37c80 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
37c90 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d   /* Database nam
37ca0 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63  e or NULL */.  c
37cb0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
37cc0 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61  eName,     /* Ta
37cd0 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f  ble name */.  co
37ce0 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
37cf0 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c  nName,    /* Col
37d00 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68  umn name */.  ch
37d10 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74  ar const **pzDat
37d20 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54  aType,    /* OUT
37d30 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61  PUT: Declared da
37d40 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61  ta type */.  cha
37d50 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c  r const **pzColl
37d60 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50  Seq,     /* OUTP
37d70 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65  UT: Collation se
37d80 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20  quence name */. 
37d90 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20   int *pNotNull, 
37da0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
37db0 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
37dc0 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
37dd0 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20  int exists */.  
37de0 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79  int *pPrimaryKey
37df0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  ,           /* O
37e00 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
37e10 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b  olumn part of PK
37e20 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f   */.  int *pAuto
37e30 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20  inc             
37e40 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
37e50 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61  e if column is a
37e60 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f  uto-increment */
37e70 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
37e80 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74  REF: Load An Ext
37e90 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ension.**.** ^Th
37ea0 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61  is interface loa
37eb0 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74  ds an SQLite ext
37ec0 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66  ension library f
37ed0 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69  rom the named fi
37ee0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  le..**.** ^The s
37ef0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
37f00 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
37f10 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f  e attempts to lo
37f20 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  ad an.** SQLite 
37f30 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
37f40 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
37f50 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a  he file zFile..*
37f60 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20  *.** ^The entry 
37f70 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a  point is zProc..
37f80 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65  ** ^zProc may be
37f90 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73   0, in which cas
37fa0 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
37fb0 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a  e entry point.**
37fc0 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71   defaults to "sq
37fd0 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f  lite3_extension_
37fe0 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73  init"..** ^The s
37ff0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
38000 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
38010 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  e returns.** [SQ
38020 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
38030 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ess and [SQLITE_
38040 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68  ERROR] if someth
38050 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
38060 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
38070 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72  occurs and pzErr
38080 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68  Msg is not 0, th
38090 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  en the.** [sqlit
380a0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
380b0 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  n()] interface s
380c0 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a  hall attempt to.
380d0 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73  ** fill *pzErrMs
380e0 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73  g with error mes
380f0 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64  sage text stored
38100 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62   in memory.** ob
38110 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
38120 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
38130 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
38140 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66  tion.** should f
38150 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20  ree this memory 
38160 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
38170 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
38180 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  ** ^Extension lo
38190 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e  ading must be en
381a0 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  abled using.** [
381b0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
381c0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
381d0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
381e0 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f  g this API,.** o
381f0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
38200 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  r will be return
38210 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
38220 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  so the [load_ext
38230 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e  ension() SQL fun
38240 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ction]..*/.int s
38250 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
38260 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
38270 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
38280 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
38290 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
382a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
382b0 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
382c0 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
382d0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
382e0 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
382f0 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
38300 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
38310 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
38320 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
38330 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
38340 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
38350 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
38360 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
38370 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
38380 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
38390 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
383a0 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
383b0 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
383c0 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74  .** ^So as not t
383d0 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
383e0 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
383f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
38400 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
38410 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
38420 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
38430 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
38440 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
38450 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
38460 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
38470 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
38480 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
38490 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70  wing API.** is p
384a0 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
384b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
384c0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
384d0 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20  echanism on and 
384e0 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  off..**.** ^Exte
384f0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
38500 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
38510 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
38520 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20  3..** ^Call the 
38530 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
38540 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
38550 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f  routine with ono
38560 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e  ff==1.** to turn
38570 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
38580 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69  ng on and call i
38590 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20  t with onoff==0 
385a0 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61  to turn.** it ba
385b0 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f  ck off again..*/
385c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
385d0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
385e0 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  on(sqlite3 *db, 
385f0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
38600 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
38610 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20  omatically Load 
38620 53 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65  Statically Linke
38630 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a  d Extensions.**.
38640 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
38650 63 65 20 63 61 75 73 65 73 20 74 68 65 20 78 45  ce causes the xE
38660 6e 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63  ntryPoint() func
38670 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
38680 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e  ed for.** each n
38690 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ew [database con
386a0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73  nection] that is
386b0 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69   created.  The i
386c0 64 65 61 20 68 65 72 65 20 69 73 20 74 68 61 74  dea here is that
386d0 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  .** xEntryPoint(
386e0 29 20 69 73 20 74 68 65 20 65 6e 74 72 79 20 70  ) is the entry p
386f0 6f 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69  oint for a stati
38700 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c  cally linked SQL
38710 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a  ite extension.**
38720 20 74 68 61 74 20 69 73 20 74 6f 20 62 65 20 61   that is to be a
38730 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61  utomatically loa
38740 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77  ded into all new
38750 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
38760 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45  tions..**.** ^(E
38770 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66  ven though the f
38780 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70  unction prototyp
38790 65 20 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e  e shows that xEn
387a0 74 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73  tryPoint() takes
387b0 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  .** no arguments
387c0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69   and returns voi
387d0 64 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  d, SQLite invoke
387e0 73 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  s xEntryPoint() 
387f0 77 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72  with three.** ar
38800 67 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65  guments and expe
38810 63 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20  cts and integer 
38820 72 65 73 75 6c 74 20 61 73 20 69 66 20 74 68 65  result as if the
38830 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68   signature of th
38840 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74  e.** entry point
38850 20 77 68 65