/ Hex Artifact Content
Login

Artifact e3e45b5c69ab3236c7ec4591a5858221863cecd4:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31c0: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
31d0: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
31e0: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
31f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3200: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3210: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3220: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3230: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3240: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3250: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
3260: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
3270: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
3280: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
3290: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
32a0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
32b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
32c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
32e0: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
32f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3300: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3310: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3320: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3330: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3350: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3360: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
3370: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
3380: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
3390: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
33a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
33c0: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
33d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
33e0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
33f0: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3400: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3410: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3420: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3430: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3440: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3450: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3460: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3470: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3480: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3490: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
34b0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
34c0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
34d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34e0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
34f0: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3500: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3520: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3530: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3550: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3560: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3580: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3590: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
35a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
35b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
35d0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
35f0: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3600: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3610: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3620: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3630: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3640: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3650: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3660: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3680: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3690: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
36a0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
36b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
36c0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
36d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
36e0: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
36f0: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3710: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3720: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3730: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3740: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3750: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3760: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3770: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3780: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3790: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
37a0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
37b0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
37c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
37d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
37e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
37f0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3800: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3810: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3820: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3830: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3840: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3850: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3860: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3870: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3880: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3890: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
38a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38b0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
38c0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
38d0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
38e0: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
38f0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3900: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3910: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3920: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3940: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3950: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3960: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3970: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3980: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3990: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
39a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
39b0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
39c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39e0: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
39f0: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3a10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3a20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3a30: 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65   close [database
3a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
3a50: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
3a60: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
3ab0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3ac0: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
3ad0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3ae0: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
3af0: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
3b00: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
3b10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3b20: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3b30: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3b60: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
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 2f 2a 20 41 6e 20            /* An 
3b90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
3ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
3bb0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3bd0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3be0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
3bf0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3c00: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3c10: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3c20: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3c30: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
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 2f 2a 20 31 73 74            /* 1st
3c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3c70: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
3c80: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **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 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3cb0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3cc0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3cd0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3ce0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
3cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
3d00: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
3d10: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3d20: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3d30: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3d40: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3d50: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3d60: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3d70: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3d80: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3d90: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3da0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
3db0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
3dc0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
3dd0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
3de0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
3df0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
3e00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
3e10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
3e20: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
3e30: 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20  sult codes],.** 
3e40: 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
3e50: 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51  _conflict()] [SQ
3e60: 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
3e70: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a  result codes]..*
3e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e90: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3ea0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3eb0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3ec0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3ed0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ee0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3ef0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3f00: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3f10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3f30: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f40: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f50: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f70: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f80: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f90: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fb0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3fc0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3fd0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fe0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3ff0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4000: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4020: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4040: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4050: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4060: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4070: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4080: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4090: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
40a0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
40c0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
40d0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40e0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40f0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4100: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4110: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4120: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4130: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4140: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4150: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4160: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4170: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4180: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
41a0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
41b0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
41c0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
41d0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41f0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4200: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4210: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4220: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4240: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4250: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4260: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4270: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4290: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
42a0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
42b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
42c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42d0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42e0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42f0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4300: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4310: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4320: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4330: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4350: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4360: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4370: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4380: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4390: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
43a0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
43b0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
43c0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43e0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43f0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4400: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4420: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4430: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4440: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4450: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4460: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4470: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4480: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
44a0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
44b0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
44c0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
44d0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44e0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44f0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4500: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4520: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4530: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4540: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4550: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4560: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4570: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4580: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4590: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
45a0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
45b0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
45c0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
45d0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45e0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45f0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4600: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4610: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4620: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4630: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4660: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4670: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4680: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4690: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
46a0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
46b0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
46c0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
46d0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46e0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4700: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4710: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4720: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4730: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4740: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4750: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4760: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4770: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4780: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4790: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
47a0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
47b0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
47c0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
47d0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47e0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47f0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4800: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4810: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4820: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4830: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4840: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4850: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4860: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4870: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4880: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4890: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
48a0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
48b0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
48c0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
48d0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48e0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48f0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4900: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4910: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4920: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4930: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4940: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4950: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4960: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4970: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4980: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4990: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
49a0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
49b0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
49c0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
49d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49e0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49f0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4a00: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4a10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4a20: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4a30: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a40: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a50: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a70: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a80: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a90: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4aa0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4ab0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4ac0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4ad0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4ae0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4af0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4b00: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b20: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4b30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b40: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b60: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b80: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ba0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4bb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4bc0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4be0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4c00: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4c20: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4c30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c40: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c60: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c80: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ca0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4cb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4cc0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ce0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4d00: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4d10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4d20: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4d30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d60: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4da0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4de0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4e20: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e60: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4ea0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ee0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4f20: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fe0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4ff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5000: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5020: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5030: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5040: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5050: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5060: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5070: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5080: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
50a0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
50b0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
50c0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
50d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
50e0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
50f0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5100: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5110: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5120: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5130: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5140: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
5160: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5180: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
51a0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
51b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
51c0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
51d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
51e0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
51f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5200: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5210: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5220: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5230: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5240: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5250: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5260: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5270: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5280: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5290: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
52a0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
52b0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
52c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
52d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
52e0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
52f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5300: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5310: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5320: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5330: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5350: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5360: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5370: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5380: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53a0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
53b0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
53c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53f0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5400: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5410: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5430: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5440: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5470: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
5480: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
5490: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
54a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
54b0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
54c0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
54d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
54e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5500: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5510: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
5520: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5540: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5550: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
5560: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5580: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5590: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
55a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
55c0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
55d0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
55e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5600: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5610: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
5620: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5640: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5650: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
5660: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5680: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5690: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
56a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
56b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
56c0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
56d0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
56e0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
56f0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5710: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
5720: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
5730: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5740: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5760: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5770: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
5780: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5790: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57b0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
57c0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
57d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
57e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5800: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
5810: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
5820: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
5830: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
5860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5870: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5880: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5890: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
58a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
58b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
58c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
58d0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
58e0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
58f0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
5900: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
5910: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5920: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5930: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5940: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5950: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5960: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5990: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
59a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
59b0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
59c0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
59d0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
59e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
59f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5a00: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5a10: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5a20: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5a30: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5a40: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5a50: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5a60: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5a70: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5a80: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5a90: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5ab0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5ac0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5ad0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5ae0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5af0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5b00: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5b10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5b20: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5b30: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5b40: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5b50: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5b60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5b70: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5b80: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5b90: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5ba0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5bb0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5bc0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5bd0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5c20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5c30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5c40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5c50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5c70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5c90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ce0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5d10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5d80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5da0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5dc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5dd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5de0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
5df0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5e10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
5e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
5e50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
5e60: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000800../*.** C
5e70: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5e80: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
5e90: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5ea0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5eb0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ec0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5ed0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5ee0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5ef0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5f00: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5f10: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5f20: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5f40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5f50: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5f60: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5f70: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f90: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5fc0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5fd0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5fe0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5ff0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6000: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6010: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6020: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6030: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6040: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6060: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6070: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6080: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6090: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
60a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
60b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
60c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
60d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
60e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
60f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6100: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6110: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6120: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6130: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6140: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6150: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6160: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6170: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6190: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
61a0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
61b0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
61c0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
61d0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
61e0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
61f0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6200: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6210: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6220: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6230: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6240: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6250: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6260: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6280: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6290: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62a0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
62b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62c0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
62d0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
62e0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
62f0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6300: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6310: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6320: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6330: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6340: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6350: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6380: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6390: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
63a0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
63b0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
63c0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
63d0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
63e0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
63f0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
6400: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
6410: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
6420: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
6430: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
6440: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
6450: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6460: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6470: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6480: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6490: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
64a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
64b0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
64c0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
64d0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
64e0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
64f0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6510: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6520: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6530: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6540: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6550: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6560: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6570: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6590: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
65a0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
65b0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
65c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
65d0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
65e0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
65f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6600: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6610: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6620: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6640: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6650: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6660: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6670: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6680: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6690: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
66a0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
66b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
66c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
66d0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
66e0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
66f0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6700: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6710: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6720: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6730: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6740: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6750: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6760: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6770: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6780: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6790: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
67a0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
67b0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
67c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
67d0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
67e0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
67f0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6800: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6810: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6820: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
6830: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6840: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6850: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6860: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6870: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6880: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6890: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
68a0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
68b0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
68c0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
68d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
68e0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
68f0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6900: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6910: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6920: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6930: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6940: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6950: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6960: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6970: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6990: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
69a0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
69b0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
69c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
69d0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
69e0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
69f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6a00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6a10: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6a20: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6a30: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6a40: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6a50: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6a60: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6a70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6a80: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6a90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6aa0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6ab0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6ac0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6ad0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6ae0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6af0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6b00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6b10: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6b20: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6b30: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6b40: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6b50: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6b60: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6b70: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6b80: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6b90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6ba0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6bb0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6bc0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6bd0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6be0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6bf0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6c00: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6c10: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6c20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6c30: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6c40: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6c50: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6c60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6c70: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6c90: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6cb0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6cd0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6ce0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6cf0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6d00: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6d10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6d20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6d30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6d40: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6d50: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6d60: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6d70: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6d80: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6d90: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6da0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6db0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6dc0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6dd0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6de0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6df0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6e00: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6e10: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6e20: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6e30: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6e40: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6e50: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6e60: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6e70: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6e80: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6e90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6ea0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6eb0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6ec0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6ee0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
6ef0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
6f00: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
6f10: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
6f20: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
6f30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
6f40: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6f50: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6f60: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6f70: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6f80: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6f90: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6fa0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6fb0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6fc0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6fd0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6fe0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
6ff0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7000: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7010: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7020: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7030: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7040: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7050: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7060: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7070: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7080: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7090: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
70a0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
70b0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
70c0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
70d0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
70e0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
70f0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7100: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7110: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7120: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7130: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7140: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7150: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7160: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7170: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7180: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7190: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
71a0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
71b0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
71c0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
71d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
71e0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
71f0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7200: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7210: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7220: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7230: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7240: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7250: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7260: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7270: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7280: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7290: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
72a0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
72b0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
72c0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
72d0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
72e0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
72f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7300: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7310: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7320: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7330: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7340: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7350: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7360: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7370: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7380: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
73b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73c0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73e0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
73f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7400: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
7410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7420: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
7430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7440: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
7450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7460: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7470: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7480: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7490: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
74a0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
74b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
74c0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
74d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
74e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
74f0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
7500: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
7510: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
7520: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
7530: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7540: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
7550: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7560: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7570: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7580: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7590: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
75a0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
75b0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
75c0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
75d0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
75e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
75f0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
7600: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
7610: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
7620: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
7630: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
7640: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
7650: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7660: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7670: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7680: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7690: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
76a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
76b0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
76c0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
76d0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
76e0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
76f0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
7700: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
7710: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
7720: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
7730: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
7740: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
7750: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7760: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7770: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7780: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7790: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
77a0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
77b0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
77c0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
77d0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
77e0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
77f0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
7800: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
7810: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
7820: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
7830: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7840: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
7850: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7860: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7870: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7880: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7890: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
78a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
78b0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
78d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
78e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
78f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7900: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7910: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7920: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7930: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7940: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7970: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7980: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7990: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
79a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
79b0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
79c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
79d0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
79e0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
79f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7a00: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7a10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7a20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7a30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7a50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7a60: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7a70: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7a80: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7a90: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7aa0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7ab0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7ac0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7ad0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7ae0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7af0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7b00: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7b10: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7b20: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7b30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7b40: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7b50: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7b60: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7b70: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7b90: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7ba0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7bb0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7bc0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7bd0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7bf0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7c00: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7c10: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7c20: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a  ersion 2 */.  /*
7c30: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7c40: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7c50: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7c60: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7c70: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7c80: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7c90: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
7ca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7cb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7cc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7cd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7ce0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7cf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7d00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7d10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7d20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7d30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
7d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7d50: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
7d60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
7d70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
7d80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
7d90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7da0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7db0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7dc0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7dd0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7de0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7df0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7e00: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7e30: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
7e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7e50: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
7e60: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
7e70: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
7e80: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
7e90: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
7ea0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
7eb0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
7ec0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
7ed0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
7ee0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
7ef0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7f00: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
7f10: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
7f20: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
7f30: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
7f40: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
7f50: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
7f60: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
7f70: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
7f80: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
7f90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
7fa0: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
7fb0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
7fc0: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
7fd0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
7fe0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
7ff0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8000: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8010: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8020: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8030: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8040: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8050: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8060: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8070: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8080: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8090: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
80a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
80b0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
80c0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
80d0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
80e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
80f0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
8100: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
8110: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
8120: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
8130: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
8140: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
8150: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
8160: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
8170: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
8180: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
8190: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
81a0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
81b0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
81c0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
81d0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
81e0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
81f0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
8200: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
8210: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
8220: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
8230: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
8240: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
8250: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ms..**.** The [S
8260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8270: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8280: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8290: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
82a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
82b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
82c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
82d0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
82e0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
82f0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
8300: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8310: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8320: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8330: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8340: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
8350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
8360: 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20  OMITTED] opcode 
8370: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
8380: 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51  ernally by.** SQ
8390: 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f  Lite and sent to
83a0: 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c   all VFSes in pl
83b0: 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f  ace of a call to
83c0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
83d0: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61  d.** when the da
83e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
83f0: 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79  n has [PRAGMA sy
8400: 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74  nchronous] set t
8410: 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65  o OFF.)^.** Some
8420: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8430: 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  es need this sig
8440: 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nal in order to 
8450: 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c  operate correctl
8460: 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d  y.** when [PRAGM
8470: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
8480: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8490: 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20  us=OFF] is set, 
84a0: 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53  but most .** VFS
84b0: 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  es do not need t
84c0: 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73  his signal and s
84d0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
84e0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
84f0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
8500: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
8510: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
8520: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
8530: 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   this.** opcode 
8540: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
8550: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
8560: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
8570: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  cialized VFSes.*
8580: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8590: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  e it.  .**.** ^T
85a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
85b0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
85c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
85d0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
85e0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
85f0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
8600: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
8610: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
8620: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
8630: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
8640: 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 74   order to work t
8650: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8660: 6e 65 73 73 20 61 67 61 69 6e 73 74 0a 2a 2a 20  ness against.** 
8670: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8680: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8690: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
86a0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
86b0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
86c0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
86d0: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
86e0: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
86f0: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
8700: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
8710: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
8720: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
8730: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
8740: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
8750: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
8760: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
8770: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
8780: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
8790: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
87a0: 20 74 68 6f 73 65 20 74 6f 20 76 61 6c 75 65 73   those to values
87b0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
87c0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
87d0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
87e0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
87f0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
8800: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
8810: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8820: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
8830: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
8840: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
8850: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
8860: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
8870: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
8880: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
8890: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
88a0: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
88b0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
88c0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
88d0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
88e0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
88f0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
8900: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
8910: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
8920: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
8930: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
8940: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
8950: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
8960: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
8970: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
8980: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
8990: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
89a0: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
89b0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
89c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
89d0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
89e0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
89f0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
8a00: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
8a10: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
8a20: 69 74 65 20 41 48 65 61 64 20 4c 6f 67 5d 20 73  ite AHead Log] s
8a30: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
8a40: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
8a50: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
8a60: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
8a70: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
8a80: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
8a90: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
8aa0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
8ab0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
8ac0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
8ad0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
8ae0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
8af0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
8b00: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
8b10: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
8b20: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
8b30: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
8b40: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
8b50: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
8b60: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
8b70: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
8b80: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
8b90: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
8ba0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
8bb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8bc0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
8bd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8be0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
8bf0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
8c00: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
8c10: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
8c20: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
8c30: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
8c40: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
8c50: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
8c60: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8c70: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
8c80: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
8c90: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
8ca0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
8cb0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
8cc0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
8cd0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
8ce0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
8cf0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
8d00: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
8d10: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
8d20: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
8d30: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
8d40: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
8d50: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
8d60: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
8d70: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
8d80: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
8d90: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
8da0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
8db0: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
8dc0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
8dd0: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
8de0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
8df0: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
8e00: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
8e10: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
8e20: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
8e30: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
8e40: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
8e50: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
8e60: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
8e70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
8e80: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
8e90: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
8ea0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
8eb0: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
8ec0: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
8ed0: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
8ee0: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
8ef0: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
8f00: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
8f10: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
8f20: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
8f30: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
8f40: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
8f50: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
8f60: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
8f70: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
8f80: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
8f90: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
8fa0: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
8fb0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8fc0: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
8fd0: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
8fe0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
8ff0: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
9000: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
9010: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
9020: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
9030: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
9040: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
9050: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
9060: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
9070: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
9080: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
9090: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
90a0: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
90b0: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
90c0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
90d0: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
90e0: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
90f0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
9100: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
9110: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
9120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9130: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
9140: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
9150: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
9160: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
9170: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
9180: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
9190: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
91a0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
91b0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
91c0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
91d0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
91e0: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
91f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
9200: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
9210: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
9220: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9230: 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69 6e  TER     7.#defin
9240: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
9250: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
9260: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
9270: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9280: 52 45 54 52 59 20 20 20 39 0a 23 64 65 66 69 6e  RETRY   9.#defin
9290: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
92a0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 31  ERSIST_WAL     1
92b0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
92c0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
92d0: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
92e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
92f0: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 31  FSNAME         1
9300: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  2../*.** CAPI3RE
9310: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
9320: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
9330: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
9340: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
9350: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
9360: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
9370: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
9380: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
9390: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
93a0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
93b0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
93c0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
93d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
93e0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
93f0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
9400: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9410: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
9420: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
9430: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
9440: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
9450: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
9460: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
9470: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
9480: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
9490: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
94a0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
94b0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
94c0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
94d0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
94e0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
94f0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
9500: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
9510: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
9520: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
9530: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
9540: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
9550: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
9560: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
9570: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
9580: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
9590: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
95a0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
95b0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
95c0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
95d0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
95e0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
95f0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
9600: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
9610: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
9620: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
9630: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
9640: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
9650: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
9660: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
9670: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
9680: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
9690: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
96a0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
96b0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
96c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
96d0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
96e0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
96f0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
9700: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
9710: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
9720: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
9730: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
9740: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
9750: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
9760: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
9770: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
9780: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
9790: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
97a0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
97b0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
97c0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
97d0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
97e0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
97f0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
9800: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
9810: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
9820: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
9830: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
9840: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
9850: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
9860: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
9870: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
9880: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
9890: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
98a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
98b0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
98c0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
98d0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
98e0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
98f0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
9900: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
9910: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
9920: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
9930: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
9940: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
9950: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
9960: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
9970: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
9980: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
9990: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
99a0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
99b0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
99c0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
99d0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
99e0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
99f0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
9a00: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
9a10: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
9a20: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
9a30: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
9a40: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
9a50: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
9a60: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
9a70: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
9a80: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
9a90: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
9aa0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
9ab0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
9ac0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
9ad0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
9ae0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
9af0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
9b00: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
9b10: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
9b20: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
9b30: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
9b40: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
9b50: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
9b60: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
9b70: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
9b80: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
9b90: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
9ba0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
9bb0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
9bc0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
9bd0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
9be0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
9bf0: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
9c00: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
9c10: 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   10 alphanumeric
9c20: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
9c30: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
9c40: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
9c50: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
9c60: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
9c70: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
9c80: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
9c90: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
9ca0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
9cb0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
9cc0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
9cd0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
9ce0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
9cf0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
9d00: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
9d10: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
9d20: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
9d30: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
9d40: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
9d50: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
9d60: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
9d70: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
9d80: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
9d90: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
9da0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
9db0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
9dc0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
9dd0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
9de0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
9df0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
9e00: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
9e10: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
9e20: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
9e30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
9e40: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
9e50: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
9e60: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
9e70: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
9e80: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
9e90: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
9ea0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
9eb0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
9ec0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
9ed0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
9ee0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
9ef0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
9f00: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
9f10: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
9f20: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
9f30: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
9f40: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
9f50: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
9f60: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
9f70: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
9f80: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
9f90: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
9fa0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
9fb0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
9fc0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
9fd0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
9fe0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
9ff0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
a000: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
a010: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
a020: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
a030: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
a040: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
a050: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
a060: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
a070: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
a080: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
a090: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
a0a0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
a0b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
a0c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
a0d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
a0e0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
a0f0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
a100: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
a110: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
a120: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
a130: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
a140: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
a150: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
a160: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
a170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
a180: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
a190: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
a1a0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
a1b0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
a1c0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
a1d0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
a1e0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
a1f0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
a200: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
a210: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
a220: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
a230: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
a240: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
a250: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
a260: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
a270: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
a280: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
a290: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
a2a0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
a2b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
a2c0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
a2d0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
a2e0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
a2f0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
a300: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
a310: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
a320: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
a330: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
a340: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
a350: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
a360: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
a370: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
a380: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
a390: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
a3a0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
a3b0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
a3c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
a3d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
a3e0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
a3f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
a400: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
a410: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
a420: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
a430: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
a440: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
a450: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
a460: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
a470: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
a480: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
a490: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
a4a0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
a4b0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
a4c0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
a4d0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
a4e0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
a4f0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
a500: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
a510: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
a520: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
a530: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
a540: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
a550: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
a560: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
a570: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
a580: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
a590: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
a5a0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
a5b0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
a5c0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
a5d0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
a5e0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
a5f0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
a600: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
a610: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
a620: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
a630: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
a640: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
a650: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
a660: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
a670: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
a680: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
a690: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
a6a0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
a6b0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
a6c0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
a6d0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
a6e0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
a6f0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
a700: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
a710: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
a720: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
a730: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
a740: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
a750: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
a760: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
a770: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
a780: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
a790: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
a7a0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
a7b0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
a7c0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
a7d0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
a7e0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
a7f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
a800: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
a810: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
a820: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
a830: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
a840: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
a850: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
a860: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
a870: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
a880: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
a890: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
a8a0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
a8b0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
a8c0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
a8d0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
a8e0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
a8f0: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
a900: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
a910: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
a920: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
a930: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
a940: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
a950: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
a960: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
a970: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
a980: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
a990: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
a9a0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
a9b0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
a9c0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
a9d0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
a9e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
a9f0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
aa00: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
aa10: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
aa20: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
aa30: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
aa40: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
aa50: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
aa60: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
aa70: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
aa80: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
aa90: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
aaa0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
aab0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
aac0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
aad0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
aae0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
aaf0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
ab00: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
ab10: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
ab20: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
ab30: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
ab40: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
ab50: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
ab60: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
ab70: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
ab80: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
ab90: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
aba0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
abb0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
abc0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
abd0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
abe0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
abf0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
ac00: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
ac10: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
ac20: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
ac30: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
ac40: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
ac50: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
ac60: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
ac70: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
ac80: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
ac90: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
aca0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
acb0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
acc0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
acd0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
ace0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
acf0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
ad00: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
ad10: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
ad20: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
ad30: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
ad40: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
ad50: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
ad60: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
ad70: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
ad80: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
ad90: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
ada0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
adb0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
adc0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
add0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
ade0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
adf0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
ae00: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
ae10: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
ae20: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
ae30: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
ae40: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
ae50: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
ae60: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
ae70: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
ae80: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
ae90: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
aea0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
aeb0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
aec0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
aed0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
aee0: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
aef0: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
af00: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
af10: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
af20: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
af30: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
af40: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
af50: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
af60: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
af70: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
af80: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
af90: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
afa0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
afb0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
afc0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
afd0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
afe0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
aff0: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
b000: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
b010: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
b020: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
b030: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
b040: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
b050: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
b060: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
b070: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
b080: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
b090: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
b0a0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
b0b0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
b0c0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
b0d0: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
b0e0: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
b0f0: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
b100: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
b110: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
b120: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
b130: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
b140: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
b150: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
b160: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
b170: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
b180: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
b190: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
b1a0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
b1b0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
b1c0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
b1d0: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
b1e0: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
b1f0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
b200: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
b210: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
b220: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
b230: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
b240: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
b250: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
b260: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
b270: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
b280: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
b290: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
b2a0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
b2b0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
b2c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
b2d0: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
b2e0: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
b2f0: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
b300: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
b310: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
b320: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
b330: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
b340: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
b350: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
b360: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
b370: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
b380: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
b390: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
b3a0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
b3b0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
b3c0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
b3d0: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
b3e0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
b3f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
b400: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
b410: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
b420: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
b430: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
b440: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
b450: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
b460: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
b470: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
b480: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
b490: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
b4a0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
b4b0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
b4c0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
b4d0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
b4e0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
b4f0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
b500: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
b510: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
b520: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
b530: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
b540: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
b550: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
b560: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
b570: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
b580: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
b590: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
b5a0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
b5b0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
b5c0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
b5d0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
b5e0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
b5f0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
b600: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
b610: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
b620: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
b630: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
b640: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
b650: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
b660: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
b670: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
b680: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
b690: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
b6a0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
b6b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
b6c0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
b6d0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
b6e0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
b6f0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
b700: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
b710: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
b720: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
b730: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
b740: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
b750: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
b760: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
b770: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
b780: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
b790: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
b7a0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
b7b0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
b7c0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
b7d0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
b7e0: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
b7f0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
b800: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
b810: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
b820: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
b830: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
b840: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
b850: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
b860: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
b870: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
b880: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
b890: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
b8a0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
b8b0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
b8c0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
b8d0: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
b8e0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
b8f0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
b900: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
b910: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
b920: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
b930: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
b940: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
b950: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
b960: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
b970: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
b980: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b990: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
b9a0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
b9b0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
b9c0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
b9d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b9e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b9f0: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
ba00: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
ba10: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
ba20: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ba30: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
ba40: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ba50: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
ba60: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
ba70: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
ba80: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
ba90: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
baa0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
bab0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
bac0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
bad0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
bae0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
baf0: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
bb00: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
bb10: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
bb20: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
bb30: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
bb40: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
bb50: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
bb60: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
bb70: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
bb80: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
bb90: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
bba0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
bbb0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
bbc0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
bbd0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
bbe0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
bbf0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
bc00: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
bc10: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
bc20: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
bc30: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
bc40: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
bc50: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
bc60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
bc70: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
bc80: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
bc90: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
bca0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
bcb0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
bcc0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
bcd0: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
bce0: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
bcf0: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
bd00: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
bd10: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
bd20: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
bd30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
bd40: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
bd50: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
bd60: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
bd70: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
bd80: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
bd90: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
bda0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
bdb0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
bdc0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
bdd0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
bde0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
bdf0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
be00: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
be10: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
be20: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
be30: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
be40: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
be50: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
be60: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
be70: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
be80: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
be90: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
bea0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
beb0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
bec0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
bed0: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
bee0: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
bef0: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
bf00: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
bf10: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
bf20: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
bf30: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
bf40: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
bf50: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
bf60: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
bf70: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
bf80: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
bf90: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
bfa0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
bfb0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
bfc0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
bfd0: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
bfe0: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
bff0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
c000: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
c010: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
c020: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
c030: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
c040: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
c050: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
c060: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
c070: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
c080: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
c090: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
c0a0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
c0b0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
c0c0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
c0d0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
c0e0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
c0f0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
c100: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
c110: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
c120: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
c130: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
c140: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
c150: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
c160: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
c170: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
c180: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
c190: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
c1a0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
c1b0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
c1c0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
c1d0: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
c1e0: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
c1f0: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
c200: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
c210: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
c220: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
c230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
c240: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
c250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c260: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
c270: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
c280: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
c290: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
c2a0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
c2b0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
c2c0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
c2d0: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
c2e0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
c2f0: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
c300: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
c310: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
c320: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
c330: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
c340: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
c350: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
c360: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
c370: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
c380: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
c390: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
c3a0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
c3b0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
c3c0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
c3d0: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
c3e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
c3f0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
c400: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
c410: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
c420: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
c430: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
c440: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
c450: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
c460: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c470: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
c480: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
c490: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
c4a0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
c4b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c4c0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
c4d0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
c4e0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
c4f0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
c500: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
c510: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
c520: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
c530: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
c540: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
c550: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
c560: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
c570: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
c580: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
c590: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
c5a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
c5b0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
c5c0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
c5d0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
c5e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c5f0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
c600: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
c610: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
c620: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
c630: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
c640: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
c650: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
c660: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
c670: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
c680: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
c690: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
c6a0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
c6b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c6c0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
c6d0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
c6e0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
c6f0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
c700: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
c710: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
c720: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
c730: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
c740: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
c750: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
c760: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c770: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
c780: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
c790: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
c7a0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
c7b0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
c7c0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
c7d0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
c7e0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
c7f0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
c800: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
c810: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
c820: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
c830: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
c840: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
c850: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
c860: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
c870: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
c880: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
c890: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
c8a0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
c8b0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
c8c0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
c8d0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
c8e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c8f0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
c900: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
c910: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
c920: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
c930: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
c940: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
c950: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c960: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
c970: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
c980: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c990: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
c9a0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
c9b0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
c9c0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
c9d0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
c9e0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
c9f0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
ca00: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ca10: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
ca20: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
ca30: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
ca40: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
ca50: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
ca60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
ca70: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
ca80: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
ca90: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
caa0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
cab0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
cac0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
cad0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
cae0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
caf0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
cb00: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
cb10: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
cb20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
cb30: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
cb40: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
cb50: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
cb60: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
cb70: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
cb80: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
cb90: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
cba0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
cbb0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
cbc0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
cbd0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
cbe0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
cbf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
cc00: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
cc10: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
cc20: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
cc30: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
cc40: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
cc50: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
cc60: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
cc70: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
cc80: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
cc90: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
cca0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
ccb0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
ccc0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
ccd0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
cce0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
ccf0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
cd00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
cd10: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
cd20: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
cd30: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
cd40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
cd50: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
cd60: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
cd70: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
cd80: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
cd90: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
cda0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
cdb0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
cdc0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
cdd0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
cde0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
cdf0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
ce00: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ce10: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ce20: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
ce30: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
ce40: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
ce50: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
ce60: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
ce70: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
ce80: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
ce90: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
cea0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ceb0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
cec0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
ced0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
cee0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
cef0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
cf00: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
cf10: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
cf20: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
cf30: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
cf40: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
cf50: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
cf60: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
cf70: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
cf80: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
cf90: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
cfa0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
cfb0: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
cfc0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
cfd0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
cfe0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
cff0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
d000: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
d010: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
d020: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
d030: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
d040: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
d050: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
d060: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
d070: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
d080: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
d090: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
d0a0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
d0b0: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
d0c0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
d0d0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
d0e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
d0f0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
d100: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
d110: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
d120: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
d130: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
d140: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
d150: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
d160: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
d170: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
d180: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
d190: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
d1a0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
d1b0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
d1c0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
d1d0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
d1e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d1f0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
d200: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
d210: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
d220: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
d230: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
d240: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
d250: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
d260: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
d270: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
d280: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
d290: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
d2a0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
d2b0: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
d2c0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
d2d0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
d2e0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
d2f0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
d300: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
d310: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
d320: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
d330: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
d340: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
d350: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
d360: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
d370: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
d380: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
d390: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
d3a0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
d3b0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
d3c0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
d3d0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
d3e0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
d3f0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
d400: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
d410: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
d420: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
d430: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
d440: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
d450: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
d460: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
d470: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
d480: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
d490: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
d4a0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
d4b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
d4c0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
d4d0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
d4e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
d4f0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
d500: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
d510: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
d520: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
d530: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
d540: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
d550: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
d560: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
d570: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
d580: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
d590: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
d5a0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
d5b0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
d5c0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
d5d0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
d5e0: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
d5f0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
d600: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
d610: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
d620: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
d630: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
d640: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
d650: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
d660: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
d670: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
d680: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
d690: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
d6a0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
d6b0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
d6c0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
d6d0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
d6e0: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
d6f0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
d700: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
d710: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
d720: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
d730: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
d740: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
d750: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
d760: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d770: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
d780: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
d790: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
d7a0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
d7b0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
d7c0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
d7d0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
d7e0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
d7f0: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
d800: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
d810: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
d820: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
d830: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
d840: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
d850: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
d860: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
d870: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
d880: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
d890: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
d8a0: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
d8b0: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
d8c0: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
d8d0: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
d8e0: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
d8f0: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
d900: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
d910: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
d920: 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
d930: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
d940: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
d950: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
d960: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
d970: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
d980: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
d990: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
d9a0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
d9b0: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
d9c0: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
d9d0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
d9e0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
d9f0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
da00: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
da10: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
da20: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
da30: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
da40: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
da50: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
da60: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
da70: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
da80: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
da90: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
daa0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
dab0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
dac0: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
dad0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
dae0: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
daf0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
db00: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
db10: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
db20: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
db30: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
db40: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
db50: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
db60: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
db70: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
db80: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
db90: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
dba0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
dbb0: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
dbc0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
dbd0: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
dbe0: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
dbf0: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
dc00: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
dc10: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
dc20: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
dc30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
dc40: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
dc50: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
dc60: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
dc70: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
dc80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
dc90: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
dca0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
dcb0: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
dcc0: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
dcd0: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
dce0: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
dcf0: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
dd00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
dd10: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
dd20: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
dd30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
dd40: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
dd50: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
dd60: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
dd70: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
dd80: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
dd90: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
dda0: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
ddb0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
ddc0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
ddd0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
dde0: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
ddf0: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
de00: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
de10: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
de20: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
de30: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
de40: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
de50: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
de60: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
de70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
de80: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
de90: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
dea0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
deb0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
dec0: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
ded0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
dee0: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
def0: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
df00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
df10: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
df20: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
df30: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
df40: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
df50: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
df60: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
df70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
df80: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
df90: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
dfa0: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
dfb0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
dfc0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
dfd0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
dfe0: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
dff0: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
e000: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
e010: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
e020: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
e030: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
e040: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
e050: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
e060: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
e070: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
e080: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
e090: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
e0a0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
e0b0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
e0c0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
e0d0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
e0e0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
e0f0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
e100: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
e110: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
e120: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
e130: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
e140: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
e150: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
e160: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
e170: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
e180: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
e190: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
e1a0: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
e1b0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
e1c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
e1d0: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
e1e0: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
e1f0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
e200: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
e210: 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
e220: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
e230: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
e240: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
e250: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
e260: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
e270: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
e280: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
e290: 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
e2a0: 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
e2b0: 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
e2c0: 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
e2d0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
e2e0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
e2f0: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
e300: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
e310: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
e320: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
e330: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
e340: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
e350: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
e360: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
e370: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
e380: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
e390: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
e3a0: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
e3b0: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
e3c0: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
e3d0: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
e3e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e3f0: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
e400: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
e410: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
e420: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
e430: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
e440: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
e450: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
e460: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
e470: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
e480: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
e490: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
e4a0: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
e4b0: 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
e4c0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
e4d0: 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
e4e0: 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
e4f0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
e500: 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
e510: 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
e520: 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
e530: 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
e540: 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
e550: 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
e560: 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
e570: 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
e580: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
e590: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
e5a0: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
e5b0: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
e5c0: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
e5d0: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
e5e0: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
e5f0: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
e600: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
e610: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
e620: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
e630: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
e640: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
e650: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
e660: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
e670: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
e680: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
e690: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
e6a0: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
e6b0: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
e6c0: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
e6d0: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
e6e0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
e6f0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
e700: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
e710: 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
e720: 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
e730: 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
e740: 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
e750: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
e760: 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
e770: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
e780: 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
e790: 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
e7a0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
e7b0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
e7c0: 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
e7d0: 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
e7e0: 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
e7f0: 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
e800: 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
e810: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
e820: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
e830: 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
e840: 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
e850: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
e860: 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
e870: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
e880: 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
e890: 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
e8a0: 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
e8b0: 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
e8c0: 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
e8d0: 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
e8e0: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
e8f0: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
e900: 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
e910: 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
e920: 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
e930: 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
e940: 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
e950: 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
e960: 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
e970: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
e980: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
e990: 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
e9a0: 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
e9b0: 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
e9c0: 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
e9d0: 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
e9e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
e9f0: 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
ea00: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
ea10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
ea20: 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
ea30: 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
ea40: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
ea50: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
ea60: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
ea70: 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
ea80: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
ea90: 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
eaa0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
eab0: 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
eac0: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
ead0: 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
eae0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
eaf0: 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
eb00: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
eb10: 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
eb20: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
eb30: 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
eb40: 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
eb50: 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
eb60: 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
eb70: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
eb80: 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
eb90: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
eba0: 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
ebb0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
ebc0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
ebd0: 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
ebe0: 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
ebf0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
ec00: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
ec10: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
ec20: 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
ec30: 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
ec40: 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
ec50: 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
ec60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ec70: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
ec80: 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
ec90: 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
eca0: 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
ecb0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
ecc0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
ecd0: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
ece0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
ecf0: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
ed00: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
ed10: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
ed20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
ed30: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
ed40: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
ed50: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ed60: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
ed70: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
ed80: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
ed90: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
eda0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
edb0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
edc0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
edd0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
ede0: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
edf0: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
ee00: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
ee10: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
ee20: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
ee30: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
ee40: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
ee50: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
ee60: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
ee70: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
ee80: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
ee90: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
eea0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
eeb0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
eec0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
eed0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
eee0: 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
eef0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
ef00: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
ef10: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
ef20: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
ef30: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
ef40: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
ef50: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
ef60: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
ef70: 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
ef80: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
ef90: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
efa0: 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
efb0: 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
efc0: 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
efd0: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
efe0: 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
eff0: 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
f000: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f010: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
f020: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
f030: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f040: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
f050: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
f060: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
f070: 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
f080: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
f090: 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
f0a0: 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
f0b0: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
f0c0: 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
f0d0: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
f0e0: 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
f0f0: 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
f100: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
f110: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
f120: 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
f130: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
f140: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
f150: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
f160: 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
f170: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
f180: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
f190: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
f1a0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
f1b0: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
f1c0: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
f1d0: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
f1e0: 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
f1f0: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
f200: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
f210: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
f220: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f230: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
f240: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
f250: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
f260: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
f270: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
f280: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
f290: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
f2a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
f2b0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
f2c0: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
f2d0: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
f2e0: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
f2f0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
f300: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
f310: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
f320: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
f330: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
f340: 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
f350: 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
f360: 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
f370: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
f380: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
f390: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
f3a0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
f3b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
f3c0: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
f3d0: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
f3e0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
f3f0: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
f400: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
f410: 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
f420: 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
f430: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
f440: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
f450: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
f460: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
f470: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
f480: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
f490: 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
f4a0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
f4b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
f4c0: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
f4d0: 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
f4e0: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
f4f0: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
f500: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
f510: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
f520: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
f530: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
f540: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
f550: 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
f560: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
f570: 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
f580: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
f590: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
f5a0: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
f5b0: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
f5c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f5d0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
f5e0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
f5f0: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
f600: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
f610: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
f620: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f630: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
f640: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
f650: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f660: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
f670: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
f680: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
f690: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
f6a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
f6b0: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
f6c0: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
f6d0: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
f6e0: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
f6f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
f700: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
f710: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
f720: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
f730: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
f740: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
f750: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f760: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
f770: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
f780: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
f790: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
f7a0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
f7b0: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
f7c0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
f7d0: 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
f7e0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
f7f0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
f800: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
f810: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
f820: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
f830: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
f840: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
f850: 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
f860: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
f870: 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
f880: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
f890: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f8a0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
f8b0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f8c0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
f8d0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
f8e0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
f8f0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
f900: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f910: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
f920: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
f930: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
f940: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
f950: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
f960: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
f970: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
f980: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
f990: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f9a0: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
f9b0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
f9c0: 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
f9d0: 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
f9e0: 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
f9f0: 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
fa00: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fa10: 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
fa20: 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
fa30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
fa40: 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
fa50: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
fa60: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
fa70: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
fa80: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
fa90: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
faa0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
fab0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
fac0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
fad0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
fae0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
faf0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
fb00: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
fb10: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
fb20: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
fb30: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
fb40: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
fb50: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
fb60: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
fb70: 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
fb80: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
fb90: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
fba0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
fbb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
fbc0: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
fbd0: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
fbe0: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
fbf0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
fc00: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
fc10: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
fc20: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
fc30: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
fc40: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
fc50: 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
fc60: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
fc70: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
fc80: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
fc90: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
fca0: 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
fcb0: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
fcc0: 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
fcd0: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
fce0: 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
fcf0: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
fd00: 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
fd10: 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
fd20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fd30: 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
fd40: 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
fd50: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
fd60: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
fd70: 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
fd80: 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
fd90: 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
fda0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
fdb0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
fdc0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
fdd0: 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
fde0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
fdf0: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
fe00: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
fe10: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
fe20: 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
fe30: 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
fe40: 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
fe50: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
fe60: 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
fe70: 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
fe80: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
fe90: 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
fea0: 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
feb0: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
fec0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
fed0: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
fee0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
fef0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
ff00: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
ff10: 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
ff20: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
ff30: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
ff40: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
ff50: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
ff60: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
ff70: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
ff80: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
ff90: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
ffa0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
ffb0: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
ffc0: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
ffd0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
ffe0: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
fff0: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
10000 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
10010 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
10020 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
10030 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
10040 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
10050 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
10060 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
10070 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
10080 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
10090 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
100a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
100b0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
100c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
100d0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
100e0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
100f0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
10100 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
10110 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
10120 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
10130 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
10140 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
10150 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
10160 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
10170 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
10180 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
10190 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
101a0 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
101b0 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
101c0 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
101d0 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
101e0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
101f0 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
10200 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
10210 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
10220 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
10230 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
10240 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
10250 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
10260 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
10270 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
10280 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
10290 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
102a0 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
102b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
102c0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
102d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
102e0 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
102f0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
10300 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
10310 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
10320 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
10330 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
10340 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
10350 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
10360 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
10370 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
10380 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
10390 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
103a0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
103b0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
103c0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
103d0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
103e0 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
103f0 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
10400 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
10410 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
10420 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
10430 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
10440 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
10450 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
10460 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
10470 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
10480 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
10490 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
104a0 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
104b0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
104c0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
104d0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
104e0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
104f0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
10500 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
10510 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
10520 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
10530 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
10540 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
10550 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
10560 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
10570 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
10580 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
10590 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
105a0 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
105b0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
105c0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
105d0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
105e0 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
105f0 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
10600 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
10610 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
10620 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
10630 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
10640 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
10650 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
10660 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
10670 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
10680 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
10690 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
106a0 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
106b0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
106c0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
106d0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
106e0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
106f0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
10700 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
10710 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
10720 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
10730 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
10740 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
10750 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
10760 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
10770 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
10780 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10790 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
107a0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
107b0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
107c0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
107d0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
107e0 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
107f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10800 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
10810 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10820 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
10830 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
10840 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
10850 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
10860 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
10870 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
10880 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
10890 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
108a0 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
108b0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
108c0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
108d0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
108e0 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
108f0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
10900 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
10910 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
10920 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
10930 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
10940 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
10950 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
10960 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
10970 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
10980 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
10990 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
109a0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
109b0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
109c0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
109d0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
109e0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
109f0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
10a00 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
10a10 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
10a20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
10a30 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
10a40 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
10a50 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
10a60 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
10a70 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
10a80 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
10a90 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
10aa0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
10ab0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
10ac0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
10ad0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
10ae0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
10af0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
10b00 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
10b10 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
10b20 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
10b30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10b40 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
10b50 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
10b60 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
10b70 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
10b80 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
10b90 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
10ba0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
10bb0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
10bc0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
10bd0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
10be0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
10bf0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
10c00 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
10c10 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
10c20 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
10c30 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
10c40 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
10c50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10c60 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
10c70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10c80 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
10c90 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10ca0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10cb0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10cc0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10cd0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
10ce0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10cf0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
10d00 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
10d10 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
10d20 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
10d30 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
10d40 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
10d50 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
10d60 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
10d70 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
10d80 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
10d90 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
10da0 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
10db0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
10dc0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
10dd0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
10de0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
10df0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10e00 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
10e10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10e20 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
10e30 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10e40 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
10e50 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
10e60 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
10e70 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
10e80 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
10e90 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
10ea0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
10eb0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
10ec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10ed0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
10ee0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
10ef0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
10f00 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
10f10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
10f20 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
10f30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10f40 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
10f50 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
10f60 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
10f70 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10f80 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10f90 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10fa0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10fb0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
10fc0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10fd0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
10fe0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
10ff0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
11000 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
11010 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
11020 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
11030 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
11040 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
11050 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
11060 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
11070 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
11080 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
11090 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
110a0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
110b0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
110c0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
110d0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
110e0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
110f0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
11100 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11110 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11120 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11130 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11140 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11150 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11160 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
11170 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
11180 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
11190 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
111a0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
111b0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
111c0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
111d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
111e0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
111f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
11200 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
11210 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
11220 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11230 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
11240 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
11250 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
11260 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11270 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11280 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
11290 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
112a0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
112b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
112c0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
112d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
112e0 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
112f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11300 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
11310 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
11320 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
11330 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
11340 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
11350 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
11360 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
11370 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
11380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11390 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
113a0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
113b0 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
113c0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
113d0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
113e0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
113f0 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
11400 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11410 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
11420 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
11430 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
11440 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
11450 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
11460 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
11470 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11480 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
11490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
114a0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
114b0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
114c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
114d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
114e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
114f0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
11500 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
11510 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
11520 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
11530 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
11540 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
11550 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
11560 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
11570 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
11580 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
11590 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
115a0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
115b0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
115c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
115d0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
115e0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
115f0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
11600 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11610 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11620 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11630 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11640 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11650 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
11660 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
11670 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
11680 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
11690 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
116a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
116b0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
116c0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
116d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
116e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
116f0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
11700 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
11710 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
11720 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
11730 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
11740 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
11750 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
11760 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
11770 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
11780 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
11790 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
117a0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
117b0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
117c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
117d0 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
117e0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
117f0 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
11800 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
11810 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
11820 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
11830 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
11840 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
11850 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
11860 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
11870 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
11880 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
11890 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
118a0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
118b0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
118c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
118d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
118e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
118f0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
11900 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
11910 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
11920 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
11930 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
11940 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
11950 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
11960 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
11970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
11980 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
11990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
119a0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
119b0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
119c0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
119d0 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
119e0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
119f0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
11a00 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
11a10 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
11a20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
11a30 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
11a40 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
11a50 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
11a60 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
11a70 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
11a80 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
11a90 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
11aa0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
11ab0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11ac0 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
11ad0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11ae0 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
11af0 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
11b00 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
11b10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
11b20 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
11b30 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
11b40 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
11b50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11b60 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
11b70 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
11b80 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e  <dd> This option
11b90 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
11ba0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
11bb0 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72   int. If non-zer
11bc0 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68  o, then.** URI h
11bd0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
11be0 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
11bf0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
11c00 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20   zero, then URI 
11c10 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67  handling.** is g
11c20 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
11c30 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e  . If URI handlin
11c40 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
11c50 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
11c60 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
11c70 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
11c80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
11c90 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
11ca0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
11cb0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
11cc0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
11cd0 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
11ce0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
11cf0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
11d00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
11d10 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
11d20 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
11d30 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
11d40 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
11d50 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49  ion is opened. I
11d60 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
11d70 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
11d80 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
11d90 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
11da0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
11db0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
11dc0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
11dd0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
11de0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
11df0 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55  d. By default, U
11e00 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
11e10 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
11e20 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
11e30 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
11e40 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
11e50 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
11e60 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
11e70 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
11e80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11e90 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
11ea0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11eb0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
11ec0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11ed0 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
11ee0 45 5f 43 4f 4e 46 4e 49 47 5f 47 45 54 50 43 41  E_CONFNIG_GETPCA
11ef0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
11f00 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
11f10 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
11f20 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
11f30 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
11f40 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
11f50 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
11f60 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
11f70 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
11f80 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
11f90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11fa0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
11fb0 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
11fc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11fd0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
11fe0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
11ff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12000 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
12010 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
12020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12030 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
12040 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
12050 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
12060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12070 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12080 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
12090 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
120a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
120b0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
120c0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
120d0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
120e0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
120f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
12100 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
12110 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
12120 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
12130 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
12140 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
12150 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
12160 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
12170 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12180 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
12190 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
121a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
121b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
121c0 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
121d0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
121e0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
121f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12200 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
12210 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
12220 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
12230 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
12240 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
12250 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
12260 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
12270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12280 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
12290 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
122a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
122b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
122c0 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
122d0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
122e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
122f0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
12300 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
12310 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
12320 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
12330 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
12340 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12350 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
12360 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
12370 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12380 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12390 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
123a0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
123b0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
123c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
123d0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
123e0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
123f0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
12400 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12410 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
12420 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
12430 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
12440 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
12450 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
12460 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
12470 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
12480 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
12490 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
124a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
124b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
124c0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
124d0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
124e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
124f0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
12500 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
12510 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
12520 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
12530 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12540 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
12550 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
12560 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
12570 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
12580 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
12590 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
125a0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
125b0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
125c0 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
125d0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
125e0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
125f0 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
12600 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
12610 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
12620 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
12630 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
12640 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
12650 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
12660 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
12670 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12680 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
12690 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
126a0 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
126b0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
126c0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
126d0 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
126e0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
126f0 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
12700 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
12710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12720 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
12730 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
12740 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
12750 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
12760 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
12770 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
12780 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
12790 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
127a0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
127b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
127c0 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
127d0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
127e0 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
127f0 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
12800 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
12810 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
12820 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
12830 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
12840 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12850 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
12860 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
12870 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
12880 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
12890 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
128a0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
128b0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
128c0 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
128d0 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
128e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
128f0 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
12900 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
12910 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
12920 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
12930 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
12940 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
12950 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
12960 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
12970 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
12980 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
12990 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
129a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
129b0 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
129c0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
129d0 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
129e0 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
129f0 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
12a00 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
12a10 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
12a20 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
12a30 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
12a40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
12a50 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
12a60 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
12a70 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
12a80 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
12a90 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
12aa0 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
12ab0 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
12ac0 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
12ad0 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
12ae0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
12af0 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
12b00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
12b10 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
12b20 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
12b30 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
12b40 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
12b50 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
12b60 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
12b70 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
12b80 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
12b90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
12ba0 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
12bb0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
12bc0 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
12bd0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
12be0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
12bf0 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
12c00 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
12c10 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
12c20 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
12c30 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
12c40 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
12c50 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
12c60 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
12c70 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
12c80 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
12c90 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
12ca0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
12cb0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
12cc0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
12cd0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
12ce0 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
12cf0 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
12d00 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
12d10 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
12d20 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
12d30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
12d40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
12d50 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
12d60 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
12d70 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
12d80 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
12d90 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
12da0 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
12db0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
12dc0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
12dd0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
12de0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
12df0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
12e00 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
12e10 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
12e20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
12e30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
12e40 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
12e50 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
12e60 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12e70 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
12e80 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
12e90 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
12ea0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
12eb0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
12ec0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
12ed0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
12ee0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
12ef0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
12f00 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
12f10 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
12f20 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
12f30 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
12f40 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
12f50 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
12f60 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
12f70 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
12f80 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
12f90 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
12fa0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
12fb0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
12fc0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
12fd0 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
12fe0 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
12ff0 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
13000 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
13010 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13020 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
13030 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
13040 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
13050 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
13060 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
13070 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
13080 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
13090 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
130a0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
130b0 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
130c0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
130d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
130e0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
130f0 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
13100 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
13110 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
13120 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
13130 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
13140 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
13150 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
13160 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
13170 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
13180 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
13190 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
131a0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
131b0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
131c0 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
131d0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
131e0 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
131f0 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
13200 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
13210 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
13220 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
13230 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
13240 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
13250 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
13260 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
13270 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
13280 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
13290 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
132a0 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
132b0 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
132c0 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
132d0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
132e0 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
132f0 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
13300 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
13310 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
13320 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
13330 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
13340 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
13350 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
13360 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
13370 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
13380 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
13390 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
133a0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
133b0 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
133c0 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
133d0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
133e0 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
133f0 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
13400 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
13410 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
13420 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
13430 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
13440 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
13450 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
13460 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
13470 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
13480 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
13490 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
134a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
134b0 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
134c0 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66  rgument.  ^As of
134d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
134e0 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74  3.7.7, this rout
134f0 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20  ines.** records 
13500 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
13510 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72  rowid of both or
13520 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e  dinary tables an
13530 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  d [virtual table
13540 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75  s]..** ^If no su
13550 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
13560 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
13570 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
13580 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13590 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
135a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  turned..**.** ^(
135b0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
135c0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
135d0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
135e0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
135f0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
13600 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
13610 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
13620 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
13630 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
13640 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
13650 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
13660 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
13670 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
13680 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
13690 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
136a0 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
136b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
136c0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
136d0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
136e0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
136f0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
13700 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
13710 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
13720 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
13730 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
13740 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
13750 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
13760 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
13770 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
13780 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
13790 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
137a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
137b0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
137c0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
137d0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
137e0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
137f0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
13800 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
13810 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
13820 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
13830 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
13840 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
13850 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
13860 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
13870 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
13880 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
13890 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
138a0 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
138b0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
138c0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
138d0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
138e0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
138f0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
13900 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
13910 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
13920 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
13930 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
13940 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
13950 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
13960 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
13970 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
13980 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
13990 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
139a0 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
139b0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
139c0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
139d0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
139e0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
139f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
13a00 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
13a10 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
13a20 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
13a30 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
13a40 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
13a50 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
13a60 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
13a70 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
13a80 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
13a90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
13aa0 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
13ab0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
13ac0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
13ad0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
13ae0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
13af0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
13b00 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
13b10 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
13b20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
13b30 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
13b40 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
13b50 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
13b60 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
13b70 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
13b80 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
13b90 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
13ba0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
13bb0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
13bc0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
13bd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
13be0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
13bf0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
13c00 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
13c10 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
13c20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
13c30 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
13c40 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
13c50 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
13c60 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
13c70 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
13c80 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
13c90 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
13ca0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
13cb0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
13cc0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
13cd0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
13ce0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
13cf0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
13d00 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
13d10 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
13d20 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
13d30 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
13d40 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
13d50 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
13d60 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
13d70 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
13d80 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
13d90 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
13da0 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
13db0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13dc0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
13dd0 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
13de0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
13df0 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
13e00 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
13e10 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
13e20 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
13e30 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
13e40 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
13e50 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
13e60 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
13e70 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
13e80 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
13e90 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
13ea0 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
13eb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
13ec0 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
13ed0 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
13ee0 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
13ef0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
13f00 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
13f10 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
13f20 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
13f30 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
13f40 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
13f50 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
13f60 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
13f70 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
13f80 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
13f90 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
13fa0 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
13fb0 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
13fc0 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
13fd0 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
13fe0 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
13ff0 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
14000 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
14010 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
14020 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
14030 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
14040 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
14050 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
14060 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
14070 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
14080 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
14090 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
140a0 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
140b0 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
140c0 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
140d0 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
140e0 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
140f0 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
14100 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
14110 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
14120 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
14130 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
14140 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
14150 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
14160 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
14170 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
14180 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
14190 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
141a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
141b0 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
141c0 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
141d0 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
141e0 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
141f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
14200 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
14210 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
14220 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
14230 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
14240 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
14250 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
14260 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
14270 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
14280 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
14290 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
142a0 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
142b0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
142c0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
142d0 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
142e0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
142f0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
14300 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
14310 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
14320 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
14330 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
14340 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
14350 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
14360 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
14370 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
14380 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
14390 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
143a0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
143b0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
143c0 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
143d0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
143e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
143f0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
14400 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
14410 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
14420 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
14430 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
14440 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
14450 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
14460 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
14470 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
14480 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
14490 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
144a0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
144b0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
144c0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
144d0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
144e0 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
144f0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
14500 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
14510 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
14520 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
14530 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
14540 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
14550 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
14560 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
14570 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
14580 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
14590 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
145a0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
145b0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
145c0 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
145d0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
145e0 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
145f0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
14600 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
14610 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
14620 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
14630 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
14640 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
14650 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
14660 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
14670 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
14680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14690 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
146a0 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72  ** ^(The count r
146b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
146c0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
146d0 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
146e0 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20  changes.** from 
146f0 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47  all [CREATE TRIG
14700 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63  GER | trigger] c
14710 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e  ontexts and chan
14720 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b  ges made by.** [
14730 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
14740 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a  ons]. However,.*
14750 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
14760 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
14770 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
14780 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d  lement [REPLACE]
14790 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
147a0 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
147b0 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
147c0 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c  g, or [DROP TABL
147d0 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20  E] processing.  
147e0 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65  The.** count doe
147f0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f  s not include ro
14800 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
14810 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
14820 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a  D OF trigger],.*
14830 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20  * though if the 
14840 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
14850 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
14860 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
14870 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61  se changes .** a
14880 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a  re counted.)^.**
14890 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f   ^The sqlite3_to
148a0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75  tal_changes() fu
148b0 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68  nction counts th
148c0 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f  e changes as soo
148d0 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74  n as.** the stat
148e0 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
148f0 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74   them is complet
14900 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
14910 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a  tement handle.**
14920 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
14930 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
14940 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
14950 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
14960 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
14970 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
14980 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
14990 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
149a0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
149b0 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
149c0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
149d0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
149e0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
149f0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
14a00 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
14a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
14a20 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
14a30 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
14a40 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
14a50 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
14a60 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
14a70 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
14a80 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
14a90 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
14aa0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
14ab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14ac0 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
14ad0 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
14ae0 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
14af0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
14b00 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
14b10 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
14b20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
14b30 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
14b40 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
14b50 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
14b60 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
14b70 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
14b80 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
14b90 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
14ba0 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
14bb0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
14bc0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
14bd0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
14be0 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
14bf0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
14c00 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
14c10 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
14c20 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
14c30 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
14c40 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
14c50 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
14c60 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
14c70 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
14c80 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
14c90 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
14ca0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
14cb0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
14cc0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
14cd0 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
14ce0 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
14cf0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
14d00 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
14d10 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
14d20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
14d30 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
14d40 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
14d50 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
14d60 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
14d70 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
14d80 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
14d90 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
14da0 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
14db0 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
14dc0 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
14dd0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
14de0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
14df0 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
14e00 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
14e10 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
14e20 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
14e30 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
14e40 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
14e50 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
14e60 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
14e70 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
14e80 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
14e90 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
14ea0 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
14eb0 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
14ec0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
14ed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
14ee0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
14ef0 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
14f00 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
14f10 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
14f20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
14f30 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
14f40 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
14f50 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
14f60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
14f70 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
14f80 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
14f90 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
14fa0 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
14fb0 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
14fc0 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
14fd0 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
14fe0 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
14ff0 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
15000 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
15010 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
15020 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
15030 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
15040 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
15050 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
15060 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
15070 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
15080 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
15090 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
150a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
150b0 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
150c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
150d0 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
150e0 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
150f0 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
15100 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
15110 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
15120 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
15130 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
15140 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
15150 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
15160 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15170 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
15180 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
15190 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
151a0 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
151b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
151c0 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
151d0 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
151e0 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
151f0 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ppen..*/.void sq
15200 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15210 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
15220 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
15230 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
15240 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
15250 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
15260 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
15270 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
15280 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
15290 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
152a0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
152b0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
152c0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
152d0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
152e0 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
152f0 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
15300 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
15310 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
15320 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
15330 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
15340 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
15350 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
15360 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
15370 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
15380 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
15390 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
153a0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
153b0 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
153c0 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
153d0 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
153e0 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
153f0 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
15400 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
15410 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
15420 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
15430 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
15440 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
15450 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
15460 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
15470 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
15480 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
15490 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
154a0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
154b0 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
154c0 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
154d0 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
154e0 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
154f0 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
15500 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
15510 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
15520 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
15530 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
15540 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
15550 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
15560 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
15570 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
15580 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
15590 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
155a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
155b0 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
155c0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
155d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
155e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
155f0 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
15600 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
15610 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
15620 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
15630 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
15640 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
15650 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
15660 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
15670 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
15680 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
15690 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
156a0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
156b0 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
156c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
156d0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
156e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
156f0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
15700 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
15710 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
15720 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
15730 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
15740 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
15750 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
15760 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
15770 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
15780 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
15790 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
157a0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
157b0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
157c0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
157d0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
157e0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
157f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
15800 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
15810 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
15820 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
15830 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
15840 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
15850 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
15860 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
15870 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
15880 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
15890 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
158a0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
158b0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
158c0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
158d0 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
158e0 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
158f0 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
15900 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
15910 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
15920 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
15930 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
15940 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
15950 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
15960 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
15970 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
15980 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
15990 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
159a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
159b0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
159c0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
159d0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
159e0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
159f0 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
15a00 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
15a10 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
15a20 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
15a30 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
15a40 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
15a50 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
15a60 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
15a70 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
15a80 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
15a90 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15aa0 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
15ab0 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
15ac0 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
15ad0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
15ae0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
15af0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
15b00 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
15b10 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
15b20 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
15b30 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
15b40 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
15b50 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
15b60 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
15b70 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
15b80 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
15b90 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
15ba0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
15bb0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
15bc0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
15bd0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
15be0 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
15bf0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
15c00 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
15c10 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
15c20 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
15c30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
15c40 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
15c50 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
15c60 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
15c70 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
15c80 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
15c90 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
15ca0 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
15cb0 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
15cc0 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
15cd0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
15ce0 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
15cf0 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
15d00 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
15d10 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
15d20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
15d30 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
15d40 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
15d50 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
15d60 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
15d70 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
15d80 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
15d90 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
15da0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
15db0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
15dc0 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
15dd0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
15de0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
15df0 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
15e00 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
15e10 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
15e20 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
15e30 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
15e40 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
15e50 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
15e60 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
15e70 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
15e80 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
15e90 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
15ea0 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
15eb0 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
15ec0 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
15ed0 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
15ee0 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
15ef0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
15f00 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
15f10 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
15f20 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
15f30 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
15f40 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
15f50 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
15f60 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
15f70 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
15f80 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
15f90 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
15fa0 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
15fb0 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
15fc0 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
15fd0 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
15fe0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
15ff0 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
16000 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
16010 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
16020 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
16030 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
16040 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
16050 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
16060 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
16070 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
16080 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
16090 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
160a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
160b0 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
160c0 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
160d0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
160e0 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
160f0 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
16100 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
16110 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
16120 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
16130 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
16140 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
16150 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
16160 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
16170 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
16180 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
16190 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
161a0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
161b0 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
161c0 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
161d0 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
161e0 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
161f0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
16200 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
16210 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
16220 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
16230 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
16240 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
16250 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
16260 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
16270 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
16280 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
16290 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
162a0 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
162b0 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
162c0 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
162d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
162e0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
162f0 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
16300 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
16310 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
16320 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
16330 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
16340 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
16350 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
16360 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
16370 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
16380 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
16390 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
163a0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
163b0 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
163c0 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
163d0 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
163e0 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
163f0 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
16400 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
16410 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
16420 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
16430 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
16440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16450 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
16460 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
16470 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
16480 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
16490 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
164a0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
164b0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
164c0 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
164d0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
164e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
164f0 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
16500 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
16510 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
16520 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
16530 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
16540 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
16550 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
16560 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
16570 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
16580 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
16590 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
165a0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
165b0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
165c0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
165d0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
165e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
165f0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
16600 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
16610 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
16620 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
16630 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
16640 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
16650 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
16660 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
16670 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
16680 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
16690 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
166a0 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
166b0 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
166c0 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
166d0 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
166e0 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
166f0 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
16700 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
16710 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
16720 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
16730 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
16740 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
16750 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
16760 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
16770 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
16780 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
16790 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
167a0 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
167b0 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
167c0 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
167d0 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
167e0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
167f0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
16800 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
16810 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
16820 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
16830 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
16840 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
16850 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
16860 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
16870 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
16880 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
16890 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
168a0 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
168b0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
168c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
168d0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
168e0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
168f0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
16900 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
16910 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
16920 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
16930 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
16940 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
16950 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
16960 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
16970 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  d.)^.*/.int sqli
16980 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
16990 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
169a0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
169b0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
169c0 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
169d0 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
169e0 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
169f0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
16a00 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
16a10 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
16a20 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
16a30 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
16a40 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
16a50 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
16a60 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
16a70 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
16a80 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
16a90 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
16aa0 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
16ab0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
16ac0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
16ad0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
16ae0 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
16af0 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
16b00 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
16b10 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
16b20 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
16b30 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
16b40 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
16b50 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
16b60 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
16b70 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
16b80 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
16b90 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
16ba0 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
16bb0 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
16bc0 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
16bd0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
16be0 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
16bf0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
16c00 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
16c10 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
16c20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
16c30 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
16c40 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
16c50 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
16c60 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
16c70 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
16c80 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
16c90 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
16ca0 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
16cb0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
16cc0 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
16cd0 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
16ce0 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
16cf0 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
16d00 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
16d10 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
16d20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
16d30 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
16d40 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
16d50 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
16d60 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
16d70 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
16d80 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
16d90 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
16da0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
16db0 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
16dc0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
16dd0 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
16de0 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
16df0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
16e00 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
16e10 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
16e20 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
16e30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
16e40 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
16e50 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
16e60 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
16e70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
16e80 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
16e90 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
16ea0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
16eb0 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
16ec0 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
16ed0 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
16ee0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
16ef0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
16f00 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
16f10 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
16f20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
16f30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
16f40 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
16f50 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
16f60 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
16f70 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
16f80 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
16f90 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16fa0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
16fb0 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
16fc0 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
16fd0 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
16fe0 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
16ff0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
17000 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
17010 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
17020 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
17030 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
17040 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
17050 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
17060 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
17070 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
17080 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
17090 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
170a0 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
170b0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
170c0 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
170d0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
170e0 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
170f0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
17100 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
17110 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
17120 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
17130 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
17140 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
17150 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
17160 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
17170 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
17180 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
17190 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
171a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
171b0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
171c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
171d0 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
171e0 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
171f0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
17200 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
17210 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
17220 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
17230 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
17240 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
17250 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
17260 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
17270 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
17280 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
17290 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
172a0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
172b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
172c0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
172d0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
172e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
172f0 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
17300 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
17310 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
17320 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
17330 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
17340 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
17350 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
17360 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
17370 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
17380 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
17390 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
173a0 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
173b0 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
173c0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
173d0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
173e0 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
173f0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
17400 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
17410 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
17420 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
17430 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
17440 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
17450 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
17460 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
17470 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
17480 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
17490 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
174a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
174b0 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
174c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
174d0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
174e0 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
174f0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
17500 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
17510 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
17520 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
17530 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
17540 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
17550 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
17560 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
17570 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
17580 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
17590 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
175a0 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
175b0 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
175c0 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
175d0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
175e0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
175f0 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
17600 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
17610 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
17620 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
17630 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
17640 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
17650 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
17660 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
17670 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
17680 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
17690 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
176a0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
176b0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
176c0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
176d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
176e0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
176f0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
17700 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
17710 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
17720 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
17730 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
17740 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
17750 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
17760 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
17770 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
17780 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
17790 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
177a0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
177b0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
177c0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
177d0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
177e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
177f0 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
17800 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
17810 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
17820 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
17830 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
17840 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
17850 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
17860 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
17870 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
17880 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
17890 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
178a0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
178b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
178c0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
178d0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
178e0 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
178f0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
17900 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
17910 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
17920 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
17930 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
17940 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
17950 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
17960 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
17970 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
17980 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
17990 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
179a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
179b0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
179c0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
179d0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
179e0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
179f0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
17a00 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
17a10 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
17a20 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
17a30 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
17a40 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17a50 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
17a60 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
17a70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
17a80 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
17a90 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
17aa0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
17ab0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
17ac0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
17ad0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
17ae0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
17af0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
17b00 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
17b10 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
17b20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
17b30 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
17b40 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
17b50 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
17b60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
17b70 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
17b80 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
17b90 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
17ba0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
17bb0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
17bc0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
17bd0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
17be0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
17bf0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
17c00 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
17c10 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
17c20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
17c30 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
17c40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
17c50 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
17c60 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
17c70 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
17c80 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
17c90 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
17ca0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
17cb0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
17cc0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
17cd0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
17ce0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
17cf0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
17d00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
17d10 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
17d20 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
17d30 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
17d40 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
17d50 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
17d60 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
17d70 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
17d80 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
17d90 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
17da0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
17db0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
17dc0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
17dd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
17de0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
17df0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
17e00 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
17e10 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
17e20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
17e30 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
17e40 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
17e50 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
17e60 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
17e70 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
17e80 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
17e90 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
17ea0 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
17eb0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
17ec0 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
17ed0 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
17ee0 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
17ef0 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
17f00 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
17f10 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
17f20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
17f30 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
17f40 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d  utes a null-term
17f50 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
17f60 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
17f70 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
17f80 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
17f90 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
17fa0 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
17fb0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
17fc0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
17fd0 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
17fe0 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
17ff0 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
18000 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
18010 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
18020 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
18030 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
18040 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
18050 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
18060 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
18070 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
18080 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
18090 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
180a0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
180b0 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
180c0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
180d0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
180e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
180f0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
18100 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
18110 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
18120 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
18130 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18140 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
18150 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
18160 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
18170 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
18180 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
18190 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
181a0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
181b0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
181c0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
181d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
181e0 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
181f0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
18200 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
18210 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
18220 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
18230 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
18240 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
18250 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
18260 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
18270 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
18280 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
18290 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
182a0 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
182b0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
182c0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
182d0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
182e0 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
182f0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
18300 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
18310 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
18320 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
18330 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
18340 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
18350 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
18360 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
18370 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
18380 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
18390 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
183a0 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
183b0 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
183c0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
183d0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
183e0 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
183f0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
18400 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
18410 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
18420 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
18430 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
18440 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
18450 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
18460 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
18470 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
18480 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
18490 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
184a0 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
184b0 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
184c0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
184d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
184e0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
184f0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
18500 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
18510 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
18520 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
18530 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
18540 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
18550 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
18560 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
18570 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
18580 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
18590 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
185a0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
185b0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
185c0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
185d0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
185e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
185f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
18600 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
18610 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
18620 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
18630 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
18640 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
18650 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
18660 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
18670 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
18680 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
18690 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
186a0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
186b0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
186c0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
186d0 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
186e0 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
186f0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
18700 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
18710 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
18720 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
18730 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
18740 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
18750 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
18760 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
18770 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
18780 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
18790 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
187a0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
187b0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
187c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
187d0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
187e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
187f0 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
18800 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
18810 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
18820 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
18830 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
18840 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
18850 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
18860 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
18870 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
18880 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
18890 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
188a0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
188b0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
188c0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
188d0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
188e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
188f0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
18900 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
18910 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
18920 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
18930 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
18940 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
18950 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
18960 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
18970 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
18980 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
18990 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
189a0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
189b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
189c0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
189d0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
189e0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
189f0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
18a00 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
18a10 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
18a20 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
18a30 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
18a40 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
18a50 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
18a60 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
18a70 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
18a80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
18a90 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
18aa0 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
18ab0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
18ac0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
18ad0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
18ae0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
18af0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
18b00 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
18b10 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
18b20 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
18b30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
18b40 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
18b50 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
18b60 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
18b70 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
18b80 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
18b90 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
18ba0 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
18bb0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
18bc0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
18bd0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
18be0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
18bf0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
18c00 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
18c10 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
18c20 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
18c30 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
18c40 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
18c50 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
18c60 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
18c70 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
18c80 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
18c90 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
18ca0 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
18cb0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
18cc0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
18cd0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
18ce0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
18cf0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
18d00 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
18d10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
18d20 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
18d30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
18d40 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
18d50 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
18d60 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
18d70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18d80 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
18d90 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
18da0 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
18db0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
18dc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
18dd0 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
18de0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
18df0 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
18e00 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
18e10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
18e20 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
18e30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
18e40 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
18e50 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
18e60 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
18e70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
18e80 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
18e90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18ea0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
18eb0 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
18ec0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18ed0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
18ee0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
18ef0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
18f00 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
18f10 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
18f20 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
18f30 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
18f40 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
18f50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18f60 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
18f70 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
18f80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
18f90 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
18fa0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
18fb0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
18fc0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
18fd0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
18fe0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
18ff0 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
19000 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
19010 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
19020 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
19030 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
19040 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
19050 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
19060 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
19070 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
19080 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
19090 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
190a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
190b0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
190c0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
190d0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
190e0 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
190f0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
19100 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
19110 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
19120 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
19130 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
19140 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
19150 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19160 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
19170 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
19180 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
19190 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
191a0 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
191b0 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
191c0 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
191d0 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
191e0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
191f0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
19200 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
19210 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
19220 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
19230 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
19240 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
19250 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
19260 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
19270 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
19280 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
19290 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
192a0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
192b0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
192c0 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
192d0 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
192e0 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
192f0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
19300 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
19310 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
19320 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
19330 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
19340 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
19350 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
19360 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
19370 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
19380 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
19390 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
193a0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
193b0 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
193c0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
193d0 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
193e0 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
193f0 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
19400 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
19410 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
19420 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
19430 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
19440 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
19450 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
19460 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
19470 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
19480 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
19490 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
194a0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
194b0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
194c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
194d0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
194e0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
194f0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
19500 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
19510 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
19520 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
19530 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
19540 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
19550 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
19560 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
19570 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
19580 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
19590 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
195a0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
195b0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
195c0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
195d0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
195e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
195f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
19600 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
19610 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
19620 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
19630 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
19640 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
19650 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
19660 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19670 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
19680 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
19690 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
196a0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
196b0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
196c0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
196d0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
196e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
196f0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
19700 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
19710 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
19720 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
19730 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
19740 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
19750 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
19760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
19770 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
19780 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
19790 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
197a0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
197b0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
197c0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
197d0 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
197e0 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
197f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
19800 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
19810 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
19820 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
19830 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
19840 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
19850 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
19860 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
19870 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
19880 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
19890 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
198a0 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
198b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
198c0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
198d0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
198e0 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
198f0 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
19900 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
19910 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19920 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
19930 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
19940 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
19950 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
19960 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
19970 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
19980 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
19990 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
199a0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
199b0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
199c0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
199d0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
199e0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
199f0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
19a00 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
19a10 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
19a20 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
19a30 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
19a40 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
19a50 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
19a60 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
19a70 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
19a80 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
19a90 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
19aa0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
19ab0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
19ac0 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
19ad0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
19ae0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
19af0 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
19b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19b10 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
19b20 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a  umber Generator.
19b30 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
19b40 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
19b50 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
19b60 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
19b70 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
19b80 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
19b90 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57  dom [ROWID | ROW
19ba0 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74  IDs] when insert
19bb0 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
19bc0 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
19bd0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
19be0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
19bf0 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20  ssible [ROWID]. 
19c00 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
19c10 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
19c20 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
19c30 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
19c40 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
19c50 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
19c60 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
19c70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
19c80 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
19c90 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
19ca0 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  poses..**.** ^A 
19cb0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
19cc0 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
19cd0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
19ce0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
19cf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
19d00 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
19d10 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  ine is invoked (
19d20 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c  either internall
19d30 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61  y or by.** the a
19d40 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20  pplication) the 
19d50 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75  PRNG is seeded u
19d60 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
19d70 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
19d80 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
19d90 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
19da0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
19db0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
19dc0 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ^On all subseque
19dd0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
19de0 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
19df0 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
19e00 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
19e10 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
19e20 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
19e30 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
19e40 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
19e50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
19e60 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
19e70 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
19e80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19e90 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
19ea0 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
19eb0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
19ec0 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
19ed0 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
19ee0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
19ef0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
19f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19f10 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
19f20 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
19f30 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
19f40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19f50 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
19f60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
19f70 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
19f80 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
19f90 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
19fa0 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
19fb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19fc0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
19fd0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
19fe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19ff0 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
1a000 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
1a010 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
1a020 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
1a030 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
1a040 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
1a050 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
1a060 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
1a070 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a080 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
1a090 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
1a0a0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
1a0b0 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
1a0c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
1a0d0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
1a0e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
1a0f0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
1a100 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1a110 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
1a120 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
1a130 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
1a140 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1a150 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
1a160 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
1a170 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
1a180 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
1a190 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
1a1a0 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
1a1b0 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
1a1c0 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
1a1d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a1e0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
1a1f0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1a200 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
1a210 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
1a220 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
1a230 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
1a240 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a250 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1a260 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1a270 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
1a280 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1a290 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1a2a0 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
1a2b0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1a2c0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1a2d0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
1a2e0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
1a2f0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
1a300 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
1a310 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1a320 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
1a330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1a340 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1a350 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1a360 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
1a370 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
1a380 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1a390 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
1a3a0 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
1a3b0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
1a3c0 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
1a3d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1a3e0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1a3f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1a400 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1a410 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1a420 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1a430 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
1a440 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
1a450 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
1a460 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1a470 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1a480 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1a490 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1a4a0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
1a4b0 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
1a4c0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1a4d0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
1a4e0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1a4f0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
1a500 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1a510 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a520 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1a530 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
1a540 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
1a550 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
1a560 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1a570 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
1a580 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1a590 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
1a5a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1a5b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
1a5c0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
1a5d0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1a5e0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
1a5f0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
1a600 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
1a610 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1a620 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
1a630 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1a640 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
1a650 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
1a660 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
1a670 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
1a680 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
1a690 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
1a6a0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
1a6b0 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
1a6c0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
1a6d0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
1a6e0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
1a6f0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1a700 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
1a710 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
1a720 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1a730 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1a740 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
1a750 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
1a760 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
1a770 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
1a780 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
1a790 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
1a7a0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
1a7b0 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
1a7c0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
1a7d0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
1a7e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1a7f0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
1a800 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
1a810 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
1a820 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
1a830 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
1a840 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
1a850 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
1a860 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
1a870 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
1a880 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
1a890 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
1a8a0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
1a8b0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
1a8c0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
1a8d0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
1a8e0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
1a8f0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
1a900 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
1a910 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
1a920 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
1a930 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
1a940 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
1a950 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1a960 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
1a970 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
1a980 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
1a990 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1a9a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
1a9b0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
1a9c0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
1a9d0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
1a9e0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
1a9f0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
1aa00 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1aa10 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
1aa20 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
1aa30 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
1aa40 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
1aa50 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
1aa60 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1aa70 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
1aa80 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
1aa90 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
1aaa0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
1aab0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
1aac0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
1aad0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1aae0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
1aaf0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
1ab00 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
1ab10 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1ab20 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
1ab30 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
1ab40 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
1ab50 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
1ab60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
1ab70 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
1ab80 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1ab90 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
1aba0 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
1abb0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
1abc0 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
1abd0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
1abe0 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
1abf0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
1ac00 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
1ac10 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
1ac20 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
1ac30 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1ac40 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
1ac50 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1ac60 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1ac70 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1ac80 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1ac90 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1aca0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1acb0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
1acc0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1acd0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1ace0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1acf0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1ad00 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1ad10 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1ad20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ad30 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1ad40 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1ad50 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1ad60 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
1ad70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ad80 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
1ad90 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
1ada0 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
1adb0 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
1adc0 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
1add0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1ade0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
1adf0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
1ae00 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
1ae10 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
1ae20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
1ae30 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
1ae40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1ae50 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
1ae60 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
1ae70 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1ae80 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
1ae90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1aea0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1aeb0 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
1aec0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1aed0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1aee0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
1aef0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
1af00 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
1af10 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
1af20 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
1af30 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
1af40 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
1af50 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
1af60 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
1af70 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
1af80 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
1af90 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
1afa0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
1afb0 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
1afc0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
1afd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1afe0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
1aff0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
1b000 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1b010 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1b020 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1b030 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
1b040 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
1b050 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b060 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
1b070 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
1b080 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1b090 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1b0a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b0b0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1b0c0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1b0d0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1b0e0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1b0f0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1b100 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1b110 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1b120 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1b130 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1b140 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1b150 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1b160 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1b170 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1b180 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1b190 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1b1a0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
1b1b0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
1b1c0 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
1b1d0 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
1b1e0 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d  K | return code]
1b1f0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  .** from the [sq
1b200 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
1b210 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
1b220 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
1b230 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
1b240 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
1b250 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
1b260 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
1b270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
1b280 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
1b290 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
1b2a0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
1b2b0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
1b2c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1b2d0 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
1b2e0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1b2f0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1b300 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
1b310 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
1b320 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1b330 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
1b340 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
1b350 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
1b360 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
1b370 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
1b380 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1b390 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1b3a0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
1b3b0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1b3c0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
1b3d0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
1b3e0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
1b3f0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
1b400 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
1b410 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1b420 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
1b430 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
1b440 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
1b450 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
1b460 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
1b470 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
1b480 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
1b490 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
1b4a0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
1b4b0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
1b4c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b4d0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
1b4e0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
1b4f0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
1b500 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
1b510 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1b520 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b530 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
1b540 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
1b550 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b560 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
1b570 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1b580 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
1b590 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
1b5a0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
1b5b0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
1b5c0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1b5d0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
1b5e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1b5f0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
1b600 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
1b610 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1b620 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
1b630 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
1b640 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
1b650 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
1b660 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
1b670 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
1b680 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
1b690 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b6a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b6b0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
1b6c0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
1b6d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b6e0 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
1b6f0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
1b700 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1b710 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b720 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b730 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
1b740 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
1b750 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1b760 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b780 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
1b790 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
1b7a0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1b7b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b7c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1b7d0 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
1b7e0 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
1b7f0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1b800 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1b820 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
1b830 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
1b840 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1b850 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1b860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1b870 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
1b880 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
1b890 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1b8a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b8b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1b8c0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
1b8d0 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
1b8e0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1b8f0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1b900 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b910 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
1b920 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
1b930 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1b940 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b950 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
1b960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b970 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1b980 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1b990 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b9a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
1b9b0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
1b9c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1b9d0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1b9e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b9f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
1ba00 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
1ba10 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1ba20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ba30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ba40 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1ba50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
1ba60 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1ba70 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ba80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ba90 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1baa0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
1bab0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bac0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1bad0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bae0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1baf0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
1bb00 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1bb10 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1bb20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1bb30 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
1bb40 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
1bb50 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1bb60 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1bb70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1bb80 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
1bb90 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
1bba0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1bbb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1bbc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1bbd0 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
1bbe0 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
1bbf0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1bc00 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1bc10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bc20 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
1bc30 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
1bc40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1bc50 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1bc60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bc70 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
1bc80 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
1bc90 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
1bca0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
1bcb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1bcc0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
1bcd0 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
1bce0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1bcf0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1bd00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
1bd10 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
1bd20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
1bd30 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
1bd40 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1bd50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
1bd60 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
1bd70 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
1bd80 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
1bd90 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1bda0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
1bdb0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1bdc0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
1bdd0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1bde0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1bdf0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
1be00 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1be10 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
1be20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1be30 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1be40 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
1be50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1be60 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
1be70 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
1be80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1be90 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
1bea0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
1beb0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1bec0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
1bed0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1bee0 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
1bef0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
1bf00 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1bf10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1bf20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1bf30 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
1bf40 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
1bf50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1bf60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1bf70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1bf80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
1bf90 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
1bfa0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bfb0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1bfc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bfd0 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
1bfe0 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
1bff0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c000 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1c010 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c020 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
1c030 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
1c040 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c050 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
1c060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c070 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
1c080 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
1c090 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1c0a0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
1c0b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c0c0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
1c0d0 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
1c0e0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
1c0f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c100 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
1c110 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
1c120 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1c130 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
1c140 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c150 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
1c160 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
1c170 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
1c180 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
1c190 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
1c1a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
1c1b0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1c1c0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1c1d0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
1c1e0 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
1c1f0 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
1c200 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1c210 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
1c220 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
1c230 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
1c240 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
1c250 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1c260 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
1c270 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
1c280 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1c290 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
1c2a0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
1c2b0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
1c2c0 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
1c2d0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1c2e0 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
1c2f0 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
1c300 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
1c310 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
1c320 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
1c330 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
1c340 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
1c350 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
1c360 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
1c370 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  igger.)^.**.** ^
1c380 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1c390 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1c3a0 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
1c3b0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
1c3c0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
1c3d0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
1c3e0 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
1c3f0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
1c400 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
1c410 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
1c420 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
1c430 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
1c440 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
1c450 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
1c460 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
1c470 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1c480 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
1c490 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
1c4a0 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
1c4b0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
1c4c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
1c4d0 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
1c4e0 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
1c4f0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
1c500 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
1c510 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
1c520 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
1c530 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
1c540 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1c550 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
1c560 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
1c570 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
1c580 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
1c590 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
1c5a0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1c5b0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
1c5c0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
1c5d0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
1c5e0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
1c5f0 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
1c600 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
1c610 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1c620 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
1c630 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
1c640 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1c650 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
1c660 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
1c670 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
1c680 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
1c690 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
1c6a0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1c6b0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
1c6c0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
1c6d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
1c6e0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
1c6f0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1c700 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
1c710 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
1c720 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
1c730 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
1c740 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
1c750 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
1c760 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1c770 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1c780 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
1c790 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1c7a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1c7b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
1c7c0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
1c7d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c7e0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
1c7f0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
1c800 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1c810 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
1c820 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
1c830 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
1c840 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
1c850 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
1c860 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
1c870 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c880 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
1c890 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
1c8a0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
1c8b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  the number of .*
1c8c0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
1c8d0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
1c8e0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
1c8f0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
1c900 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
1c910 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
1c920 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e  lback X..**.** ^
1c930 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
1c940 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
1c950 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
1c960 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
1c970 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c980 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
1c990 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
1c9a0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
1c9b0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
1c9c0 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
1c9d0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
1c9e0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
1c9f0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
1ca00 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1ca10 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
1ca20 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
1ca30 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
1ca40 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
1ca50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
1ca60 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
1ca70 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1ca80 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
1ca90 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
1caa0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
1cab0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
1cac0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
1cad0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
1cae0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
1caf0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
1cb00 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
1cb10 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
1cb20 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1cb30 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1cb40 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1cb50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1cb60 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1cb70 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1cb80 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
1cb90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cba0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1cbb0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1cbc0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1cbd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1cbe0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1cbf0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1cc00 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1cc10 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
1cc20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1cc30 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1cc40 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
1cc50 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
1cc60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cc70 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
1cc80 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
1cc90 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
1cca0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
1ccb0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1ccc0 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
1ccd0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
1cce0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
1ccf0 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
1cd00 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
1cd10 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
1cd20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1cd30 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1cd40 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
1cd50 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1cd60 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
1cd70 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
1cd80 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
1cd90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cda0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
1cdb0 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
1cdc0 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
1cdd0 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
1cde0 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
1cdf0 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
1ce00 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
1ce10 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1ce20 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
1ce30 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
1ce40 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
1ce50 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
1ce60 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
1ce70 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
1ce80 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
1ce90 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
1cea0 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
1ceb0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
1cec0 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
1ced0 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
1cee0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
1cef0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
1cf00 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1cf10 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1cf20 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
1cf30 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1cf40 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
1cf50 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
1cf60 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
1cf70 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
1cf80 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
1cf90 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
1cfa0 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
1cfb0 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
1cfc0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
1cfd0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
1cfe0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
1cff0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
1d000 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
1d010 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
1d020 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
1d030 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1d040 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1d050 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
1d060 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1d070 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
1d080 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1d090 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
1d0a0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
1d0b0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
1d0c0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
1d0d0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
1d0e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1d0f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1d100 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1d110 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
1d120 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
1d130 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
1d140 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
1d150 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
1d160 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
1d170 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
1d180 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
1d190 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
1d1a0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
1d1b0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
1d1c0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
1d1d0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
1d1e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
1d1f0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
1d200 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1d210 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
1d220 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
1d230 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1d240 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
1d250 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
1d260 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
1d270 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
1d280 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
1d290 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1d2a0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1d2b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1d2c0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1d2d0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1d2e0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
1d2f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1d300 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
1d310 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
1d320 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
1d330 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1d340 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
1d350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1d360 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1d370 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
1d380 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
1d390 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1d3a0 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
1d3b0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1d3c0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1d3d0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1d3e0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1d3f0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1d400 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1d410 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1d420 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1d430 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
1d440 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
1d450 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
1d460 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
1d470 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1d480 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
1d490 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
1d4a0 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
1d4b0 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
1d4c0 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
1d4d0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1d4e0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1d4f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1d500 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
1d510 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
1d520 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1d530 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1d540 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1d550 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
1d560 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
1d570 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
1d580 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
1d590 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
1d5a0 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
1d5b0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1d5c0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1d5d0 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
1d5e0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
1d5f0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
1d600 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d610 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
1d620 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
1d630 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1d640 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
1d650 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1d660 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
1d670 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1d680 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
1d690 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
1d6a0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1d6b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1d6c0 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
1d6d0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
1d6e0 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
1d6f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d700 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
1d710 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
1d720 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
1d730 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
1d740 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
1d750 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
1d760 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
1d770 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1d780 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
1d790 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1d7a0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
1d7b0 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
1d7c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d7d0 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
1d7e0 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
1d7f0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1d800 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
1d810 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
1d820 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
1d830 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
1d840 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1d850 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
1d860 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1d870 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1d880 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1d890 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
1d8a0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
1d8b0 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
1d8c0 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
1d8d0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1d8e0 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
1d8f0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
1d900 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
1d910 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
1d920 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
1d930 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
1d940 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
1d950 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1d960 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1d970 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
1d980 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
1d990 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
1d9a0 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
1d9b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
1d9c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1d9d0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1d9e0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1d9f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1da00 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1da10 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1da20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1da30 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1da40 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1da50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1da60 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
1da70 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1da80 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1da90 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1daa0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1dab0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1dac0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
1dad0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1dae0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1daf0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1db00 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1db10 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1db20 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1db30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1db40 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1db50 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1db60 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1db70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1db80 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1db90 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1dba0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1dbb0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1dbc0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1dbd0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1dbe0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1dbf0 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1dc00 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1dc10 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1dc20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1dc30 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1dc40 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1dc50 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1dc60 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1dc70 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1dc80 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1dc90 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1dca0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1dcb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1dcc0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1dcd0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1dce0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1dcf0 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1dd00 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1dd10 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
1dd20 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
1dd30 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
1dd40 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
1dd50 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
1dd60 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1dd70 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1dd80 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
1dd90 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
1dda0 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
1ddb0 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
1ddc0 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
1ddd0 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
1dde0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
1ddf0 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
1de00 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1de10 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
1de20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
1de30 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
1de40 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
1de50 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
1de60 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
1de70 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
1de80 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1de90 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
1dea0 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
1deb0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
1dec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ded0 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
1dee0 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
1def0 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
1df00 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
1df10 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
1df20 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
1df30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
1df40 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
1df50 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
1df60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1df70 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
1df80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1df90 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
1dfa0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1dfb0 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
1dfc0 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
1dfd0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
1dfe0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1dff0 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
1e000 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
1e010 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
1e020 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
1e030 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
1e040 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1e050 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
1e060 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
1e070 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
1e080 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
1e090 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
1e0a0 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
1e0b0 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
1e0c0 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
1e0d0 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
1e0e0 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
1e0f0 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
1e100 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
1e110 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
1e120 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
1e130 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
1e140 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
1e150 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
1e160 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
1e170 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
1e180 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
1e190 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
1e1a0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
1e1b0 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
1e1c0 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
1e1d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
1e1e0 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
1e1f0 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
1e200 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
1e210 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
1e220 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
1e230 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
1e240 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1e250 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
1e260 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
1e270 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
1e280 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
1e290 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
1e2a0 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
1e2b0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
1e2c0 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
1e2d0 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
1e2e0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
1e2f0 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
1e300 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74  * ^On windows, t
1e310 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
1e320 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
1e330 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
1e340 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
1e350 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
1e360 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
1e370 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
1e380 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
1e390 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
1e3a0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
1e3b0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
1e3c0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
1e3d0 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
1e3e0 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
1e3f0 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
1e400 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
1e410 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
1e420 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
1e430 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1e440 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1e450 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1e460 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
1e470 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
1e480 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1e490 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
1e4a0 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
1e4b0 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
1e4c0 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
1e4d0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1e4e0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1e4f0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
1e500 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
1e510 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
1e520 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
1e530 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
1e540 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
1e550 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
1e560 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
1e570 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
1e580 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
1e590 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
1e5a0 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
1e5b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e5c0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
1e5d0 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
1e5e0 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
1e5f0 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
1e600 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
1e610 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
1e620 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
1e630 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
1e640 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
1e650 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
1e660 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e670 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
1e680 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
1e690 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
1e6a0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
1e6b0 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
1e6c0 20 6f 72 0a 2a 2a 20 20 20 20 20 22 72 77 63 22   or.**     "rwc"
1e6d0 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
1e6e0 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
1e6f0 68 65 72 20 76 61 6c 75 65 20 69 73 20 61 6e 20  her value is an 
1e700 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
1e710 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
1e720 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
1e730 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1e740 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
1e750 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
1e760 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
1e770 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1e780 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
1e790 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
1e7a0 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
1e7b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1e7c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2e  e3_prepare_v2().
1e7d0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
1e7e0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
1e7f0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
1e800 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1e810 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1e820 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
1e830 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
1e840 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
1e850 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1e860 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
1e870 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1e880 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
1e890 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
1e8a0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
1e8b0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
1e8c0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
1e8d0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1e8e0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
1e8f0 5f 43 52 45 41 54 45 2e 20 5e 49 66 20 73 71 6c  _CREATE. ^If sql
1e900 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1e910 73 20 0a 2a 2a 20 20 20 20 20 75 73 65 64 2c 20  s .**     used, 
1e920 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  it is an error t
1e930 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
1e940 65 20 66 6f 72 20 74 68 65 20 6d 6f 64 65 20 70  e for the mode p
1e950 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
1e960 20 0a 2a 2a 20 20 20 20 20 6c 65 73 73 20 72 65   .**     less re
1e970 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
1e980 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
1e990 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
1e9a0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 0a  d as the third .
1e9b0 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
1e9c0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
1e9d0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
1e9e0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
1e9f0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
1ea00 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
1ea10 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
1ea20 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
1ea30 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
1ea40 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1ea50 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
1ea60 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
1ea70 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
1ea80 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
1ea90 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
1eaa0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
1eab0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
1eac0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
1ead0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
1eae0 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
1eaf0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1eb00 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
1eb10 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
1eb20 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
1eb30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1eb40 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
1eb50 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
1eb60 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
1eb70 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
1eb80 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
1eb90 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
1eba0 62 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73  behaviour reques
1ebb0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
1ebc0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
1ebd0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
1ebe0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
1ebf0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
1ec00 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
1ec10 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
1ec20 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
1ec30 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
1ec40 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
1ec50 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
1ec60 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
1ec70 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1ec80 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
1ec90 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
1eca0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
1ecb0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
1ecc0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
1ecd0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
1ece0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
1ecf0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
1ed00 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
1ed10 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
1ed20 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
1ed30 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1ed40 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
1ed50 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
1ed60 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
1ed70 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
1ed80 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
1ed90 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
1eda0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
1edb0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
1edc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
1edd0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
1ede0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
1edf0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
1ee00 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
1ee10 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1ee20 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
1ee30 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
1ee40 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
1ee50 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
1ee60 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
1ee70 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1ee80 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
1ee90 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1eea0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1eeb0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
1eec0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
1eed0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
1eee0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
1eef0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
1ef00 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
1ef10 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
1ef20 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
1ef30 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
1ef40 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
1ef50 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
1ef60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
1ef70 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
1ef80 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
1ef90 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
1efa0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
1efb0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
1efc0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
1efd0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
1efe0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
1eff0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
1f000 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
1f010 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
1f020 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
1f030 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
1f040 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
1f050 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
1f060 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
1f070 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
1f080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1f090 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
1f0a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
1f0b0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
1f0c0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
1f0d0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
1f0e0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
1f0f0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
1f100 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
1f110 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
1f120 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
1f130 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1f140 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1f150 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
1f160 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
1f170 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
1f180 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
1f190 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
1f1a0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
1f1b0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
1f1c0 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a  ix-nolock <td>.*
1f1d0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1f1e0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
1f1f0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
1f200 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
1f210 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a  unix-nolock"..**
1f220 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1f230 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
1f240 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
1f250 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
1f260 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
1f270 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
1f280 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
1f290 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
1f2a0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
1f2b0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
1f2c0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
1f2d0 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
1f2e0 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
1f2f0 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
1f300 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
1f310 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
1f320 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
1f330 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
1f340 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
1f350 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
1f360 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
1f370 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
1f380 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
1f390 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
1f3a0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
1f3b0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
1f3c0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
1f3d0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
1f3e0 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
1f3f0 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
1f400 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
1f410 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
1f420 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
1f430 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
1f440 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
1f450 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
1f460 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
1f470 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
1f480 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
1f490 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
1f4a0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
1f4b0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
1f4c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
1f4d0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1f4e0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1f4f0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1f500 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1f510 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1f520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1f530 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1f540 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1f550 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1f560 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1f570 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1f580 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1f590 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1f5a0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1f5b0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1f5c0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1f5d0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1f5e0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1f5f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1f600 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f610 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1f620 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1f630 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1f640 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1f650 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1f660 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1f670 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1f680 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1f690 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1f6a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1f6b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1f6c0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1f6d0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1f6e0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1f6f0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1f700 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1f710 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1f720 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1f730 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1f740 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1f750 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1f760 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1f770 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1f780 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1f790 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1f7a0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1f7b0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1f7c0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1f7d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1f7e0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1f7f0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1f800 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1f810 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
1f820 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
1f830 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
1f840 2a 2a 20 54 68 69 73 20 69 73 20 61 20 75 74 69  ** This is a uti
1f850 6c 69 74 79 20 72 6f 75 74 69 6e 65 2c 20 75 73  lity routine, us
1f860 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
1f870 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
1f880 74 20 63 68 65 63 6b 73 0a 2a 2a 20 74 6f 20 73  t checks.** to s
1f890 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
1f8a0 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
1f8b0 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
1f8c0 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
1f8d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
1f8e0 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
1f8f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
1f900 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
1f910 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 46 69  r..**.** The zFi
1f920 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1f930 69 73 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  is the filename 
1f940 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
1f950 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a  nto the xOpen().
1f960 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 56  ** method of a V
1f970 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1f980 6e 2e 20 20 54 68 65 20 7a 50 61 72 61 6d 20 61  n.  The zParam a
1f990 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
1f9a0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 71 75  ame of the.** qu
1f9b0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 77 65  ery parameter we
1f9c0 20 73 65 65 6b 2e 20 20 54 68 69 73 20 72 6f 75   seek.  This rou
1f9d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1f9e0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 7a 50   value of the zP
1f9f0 61 72 61 6d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  aram.** paramete
1fa00 72 20 69 66 20 69 74 20 65 78 69 73 74 73 2e 20  r if it exists. 
1fa10 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
1fa20 72 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  r does not exist
1fa30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  , this routine.*
1fa40 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
1fa50 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1fa60 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
1fa70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
1fa80 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f  s function is no
1fa90 74 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  t a pointer that
1faa0 20 53 51 4c 69 74 65 0a 2a 2a 20 70 61 73 73 65   SQLite.** passe
1fab0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
1fac0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
1fad0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
1fae0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  f this routine.*
1faf0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  * is undefined a
1fb00 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
1fb10 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
1fb20 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1fb30 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
1fb40 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
1fb50 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
1fb60 2a 7a 50 61 72 61 6d 29 3b 0a 0a 0a 2f 2a 0a 2a  *zParam);.../*.*
1fb70 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1fb80 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1fb90 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1fba0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1fbb0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1fbc0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1fbd0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1fbe0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1fbf0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1fc00 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1fc10 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1fc20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1fc30 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1fc40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fc50 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1fc60 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1fc70 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1fc80 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1fc90 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1fca0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1fcb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1fcc0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1fcd0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1fce0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1fcf0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1fd00 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1fd10 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1fd20 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1fd30 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1fd40 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1fd50 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1fd60 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1fd70 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1fd80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1fd90 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1fda0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1fdb0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1fdc0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1fdd0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1fde0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1fdf0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1fe00 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1fe10 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1fe20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1fe30 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1fe40 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1fe50 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1fe60 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1fe70 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1fe80 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1fe90 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1fea0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1feb0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1fec0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1fed0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1fee0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1fef0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1ff00 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1ff10 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1ff20 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1ff30 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1ff40 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1ff50 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1ff60 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1ff70 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1ff80 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1ff90 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1ffa0 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1ffb0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1ffc0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1ffd0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1ffe0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1fff0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
20000 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
20010 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
20020 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
20030 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
20040 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
20050 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
20060 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
20070 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
20080 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
20090 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
200a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
200b0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
200c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
200d0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
200e0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
200f0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
20100 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
20110 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
20120 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
20130 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
20140 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
20150 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
20160 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
20170 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
20180 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
20190 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
201a0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
201b0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
201c0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
201d0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
201e0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
201f0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
20200 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
20210 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
20220 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
20230 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
20240 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
20250 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
20260 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
20270 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
20280 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
20290 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
202a0 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
202b0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
202c0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
202d0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
202e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
202f0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
20300 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
20310 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
20320 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
20330 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
20340 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
20350 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
20360 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
20370 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
20380 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
20390 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
203a0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
203b0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
203c0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
203d0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
203e0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
203f0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
20400 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
20410 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
20420 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
20430 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
20440 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
20450 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
20460 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
20470 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
20480 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
20490 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
204a0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
204b0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
204c0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
204d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
204e0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
204f0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
20500 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
20510 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20520 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
20530 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
20540 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
20550 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
20560 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
20570 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
20580 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
20590 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
205a0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
205b0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
205c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
205d0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
205e0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
205f0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
20600 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
20610 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
20620 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
20630 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
20640 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
20650 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
20660 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
20670 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
20680 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
20690 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
206a0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
206b0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
206c0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
206d0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
206e0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
206f0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
20700 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
20710 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
20720 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20730 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
20740 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
20750 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
20760 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20770 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
20780 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
20790 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
207a0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
207b0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
207c0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
207d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
207e0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
207f0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
20800 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
20810 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
20820 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
20830 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
20840 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
20850 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
20860 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
20870 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
20880 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
20890 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
208a0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
208b0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
208c0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
208d0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
208e0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
208f0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
20900 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
20910 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
20920 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
20930 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
20940 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
20950 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
20960 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
20970 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
20980 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
20990 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
209a0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
209b0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
209c0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
209d0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
209e0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
209f0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
20a00 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
20a10 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
20a20 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
20a30 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
20a40 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
20a50 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
20a60 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
20a70 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
20a80 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
20a90 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
20aa0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
20ab0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
20ac0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
20ad0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
20ae0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
20af0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
20b00 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
20b10 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
20b20 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
20b30 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
20b40 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
20b50 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
20b60 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
20b70 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
20b80 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
20b90 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
20ba0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
20bb0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
20bc0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
20bd0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
20be0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
20bf0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
20c00 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
20c10 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
20c20 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
20c30 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
20c40 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
20c50 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
20c60 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
20c70 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
20c80 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
20c90 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
20ca0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
20cb0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
20cc0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
20cd0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
20ce0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
20cf0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
20d00 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
20d10 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
20d20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
20d30 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
20d40 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
20d50 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
20d60 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
20d70 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
20d80 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
20d90 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
20da0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
20db0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
20dc0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
20dd0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
20de0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
20df0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
20e00 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
20e10 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
20e20 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
20e30 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
20e40 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
20e50 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
20e60 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
20e70 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
20e80 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
20e90 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
20ea0 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
20eb0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
20ec0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
20ed0 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
20ee0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
20ef0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
20f00 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
20f10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20f20 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
20f30 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
20f40 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
20f50 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
20f60 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
20f70 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
20f80 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
20f90 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
20fa0 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
20fb0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
20fc0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
20fd0 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
20fe0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
20ff0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
21000 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
21010 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
21020 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
21030 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
21040 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
21050 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
21060 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
21070 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
21080 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
21090 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
210a0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
210b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
210c0 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
210d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
210e0 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
210f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
21100 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
21110 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
21120 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
21130 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
21140 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
21150 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
21160 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
21170 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
21180 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
21190 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
211a0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
211b0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
211c0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
211d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
211e0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
211f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
21200 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
21210 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21220 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
21230 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
21240 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
21250 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
21260 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
21270 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
21280 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
21290 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
212a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
212b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
212c0 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
212d0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
212e0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
212f0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
21300 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
21310 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
21320 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
21330 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
21340 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
21350 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
21360 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
21370 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
21380 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
21390 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
213a0 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
213b0 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
213c0 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
213d0 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
213e0 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
213f0 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
21400 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
21410 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
21420 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
21430 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
21440 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
21450 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
21460 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
21470 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
21480 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
21490 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
214a0 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
214b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
214c0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
214d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
214e0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
214f0 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
21500 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
21510 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
21520 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
21530 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
21540 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
21550 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
21560 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
21570 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21580 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
21590 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
215a0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
215b0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
215c0 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
215d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
215e0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
215f0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
21600 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
21610 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
21620 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
21630 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
21640 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
21650 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
21660 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
21670 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
21680 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
21690 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
216a0 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
216b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
216c0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
216d0 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
216e0 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
216f0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
21700 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
21710 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
21720 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
21730 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
21740 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
21750 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
21760 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
21770 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
21780 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
21790 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
217a0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
217b0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
217c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
217d0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
217e0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
217f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
21800 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
21810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
21820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
21830 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
21840 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
21850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21860 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
21870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21880 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
21890 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
218a0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
218b0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
218c0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
218d0 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
218e0 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
218f0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
21900 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
21910 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
21920 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
21930 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
21940 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
21950 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
21960 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
21970 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
21980 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
21990 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
219a0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
219b0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
219c0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
219d0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
219e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
219f0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
21a00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21a10 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
21a20 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
21a30 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
21a40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
21a50 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
21a60 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
21a70 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
21a80 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
21a90 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
21aa0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
21ab0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
21ac0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
21ad0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
21ae0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
21af0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
21b00 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
21b10 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
21b20 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
21b30 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
21b40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
21b50 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
21b60 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
21b70 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
21b80 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
21b90 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
21ba0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
21bb0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
21bc0 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
21bd0 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
21be0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
21bf0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
21c00 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
21c10 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
21c20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
21c30 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
21c40 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
21c50 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
21c60 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
21c70 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
21c80 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
21c90 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
21ca0 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
21cb0 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
21cc0 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
21cd0 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
21ce0 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
21cf0 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
21d00 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
21d10 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
21d20 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
21d30 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
21d40 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
21d50 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
21d60 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
21d70 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
21d80 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
21d90 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
21da0 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
21db0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
21dc0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
21dd0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
21de0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
21df0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
21e00 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20  s as this saves 
21e10 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69  SQLite from havi
21e20 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20  ng to.** make a 
21e30 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75  copy of the inpu
21e40 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
21e50 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
21e60 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
21e70 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
21e80 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
21e90 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
21ea0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
21eb0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
21ec0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
21ed0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
21ee0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
21ef0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
21f00 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
21f10 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
21f20 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
21f30 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
21f40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
21f50 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
21f60 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
21f70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21f80 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
21f90 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
21fa0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
21fb0 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
21fc0 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
21fd0 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
21fe0 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
21ff0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
22000 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
22010 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
22020 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
22030 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
22040 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
22050 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
22060 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
22070 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
22080 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
22090 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
220a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
220b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
220c0 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
220d0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
220e0 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
220f0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
22100 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
22110 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
22120 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
22130 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
22140 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
22150 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
22160 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
22170 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
22180 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22190 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
221a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
221b0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
221c0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
221d0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
221e0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
221f0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
22200 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
22210 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
22220 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
22230 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
22240 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
22250 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
22260 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
22270 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22280 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
22290 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
222a0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
222b0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
222c0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
222d0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
222e0 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
222f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22300 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
22310 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
22320 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
22330 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
22340 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
22350 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
22360 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
22370 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
22380 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
22390 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
223a0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
223b0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
223c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
223d0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
223e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
223f0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
22400 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  again..** </li>.
22410 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
22420 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
22430 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
22440 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
22450 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
22460 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
22470 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
22480 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
22490 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
224a0 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
224b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
224c0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
224d0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
224e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
224f0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
22500 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
22510 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
22520 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
22530 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
22540 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
22550 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
22560 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
22570 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
22580 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
22590 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
225a0 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
225b0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
225c0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
225d0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
225e0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
225f0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
22600 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
22610 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
22620 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
22630 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
22640 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
22650 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
22660 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
22670 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
22680 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
22690 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
226a0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
226b0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
226c0 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
226d0 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
226e0 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
226f0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
22700 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
22710 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
22720 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
22730 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22740 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
22750 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
22760 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
22770 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
22780 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
22790 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
227a0 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
227b0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
227c0 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
227d0 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
227e0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
227f0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
22800 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
22810 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
22820 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
22830 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
22840 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
22850 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
22860 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
22870 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
22880 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f  d..** the .** </
22890 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
228a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
228b0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
228c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
228d0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
228e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
228f0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
22900 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22910 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
22920 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
22930 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
22940 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
22950 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
22960 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
22970 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
22980 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
22990 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
229a0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
229b0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
229c0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
229d0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
229e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
229f0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
22a00 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
22a10 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
22a20 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
22a30 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
22a40 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
22a50 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
22a60 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
22a70 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
22a80 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
22a90 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
22aa0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
22ab0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
22ac0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
22ad0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
22ae0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
22af0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
22b00 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
22b10 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
22b20 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
22b30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
22b40 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
22b50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
22b60 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
22b70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
22b80 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
22b90 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
22ba0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
22bb0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
22bc0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
22bd0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
22be0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
22bf0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
22c00 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
22c10 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
22c20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
22c30 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
22c40 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
22c50 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
22c60 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
22c70 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
22c80 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
22c90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
22ca0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
22cb0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
22cc0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
22cd0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
22ce0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
22cf0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
22d00 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
22d10 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
22d20 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
22d30 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
22d40 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
22d50 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
22d60 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
22d70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
22d80 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
22d90 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
22da0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
22db0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
22dc0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
22dd0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
22de0 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
22df0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
22e00 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
22e10 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
22e20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
22e30 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
22e40 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
22e50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
22e60 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
22e70 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
22e80 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
22e90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22ea0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
22eb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
22ec0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
22ed0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
22ee0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
22ef0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22f00 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
22f10 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
22f20 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
22f30 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
22f40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
22f50 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
22f60 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
22f70 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
22f80 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
22f90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22fa0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
22fb0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
22fc0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
22fd0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
22fe0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
22ff0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
23000 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
23010 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
23020 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
23030 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
23040 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
23050 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
23060 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
23070 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
23080 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
23090 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
230a0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
230b0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
230c0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
230d0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
230e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
230f0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
23100 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23110 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
23120 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
23130 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
23140 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
23150 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
23160 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
23170 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
23180 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
23190 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
231a0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
231b0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
231c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
231d0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
231e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
231f0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
23200 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
23210 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
23220 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
23230 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
23240 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
23250 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
23260 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
23270 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
23280 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
23290 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
232a0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
232b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
232c0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
232d0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
232e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
232f0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
23300 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
23310 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
23320 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
23330 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
23340 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
23350 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
23360 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
23370 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
23380 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
23390 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
233a0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
233b0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
233c0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
233d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
233e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
233f0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
23400 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
23410 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
23420 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
23430 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
23440 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23450 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
23460 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
23470 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23480 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
23490 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
234a0 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
234b0 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
234c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
234d0 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
234e0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
234f0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
23500 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
23510 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
23520 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
23530 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
23540 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
23550 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
23560 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
23570 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
23580 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
23590 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
235a0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
235b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
235c0 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
235d0 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
235e0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
235f0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
23600 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
23610 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
23620 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
23630 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
23640 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
23650 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
23660 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
23670 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
23680 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
23690 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
236a0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
236b0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
236c0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
236d0 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
236e0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
236f0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
23700 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
23710 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
23720 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
23730 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
23740 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
23750 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
23760 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
23770 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
23780 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
23790 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
237a0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
237b0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
237c0 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
237d0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
237e0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
237f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
23800 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
23810 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
23820 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
23830 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
23840 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
23850 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
23860 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
23870 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
23880 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
23890 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
238a0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
238b0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
238c0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
238d0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
238e0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
238f0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
23900 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
23910 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
23920 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
23930 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
23940 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
23950 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
23960 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
23970 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
23980 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
23990 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
239a0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
239b0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
239c0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
239d0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
239e0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
239f0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
23a00 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
23a10 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
23a20 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
23a30 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
23a40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
23a50 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
23a60 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
23a70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
23a80 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
23a90 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
23aa0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
23ab0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
23ac0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
23ad0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
23ae0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
23af0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
23b00 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
23b10 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
23b20 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
23b30 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
23b40 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
23b50 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
23b60 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
23b70 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
23b80 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
23b90 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
23ba0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
23bb0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
23bc0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
23bd0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
23be0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
23bf0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
23c00 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
23c10 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
23c20 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
23c30 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
23c40 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
23c50 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
23c60 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
23c70 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
23c80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
23c90 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
23ca0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
23cb0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
23cc0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
23cd0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
23ce0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
23cf0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
23d00 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
23d10 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
23d20 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
23d30 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
23d40 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
23d50 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
23d60 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
23d70 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
23d80 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
23d90 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
23da0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
23db0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
23dc0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
23dd0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
23de0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23df0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
23e00 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
23e10 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
23e20 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
23e30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
23e40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
23e50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
23e60 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
23e70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23e80 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
23e90 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
23ea0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
23eb0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
23ec0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
23ed0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23ee0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
23ef0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
23f00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
23f10 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
23f20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
23f30 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
23f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
23f50 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
23f60 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
23f70 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
23f80 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
23f90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23fa0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
23fb0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
23fc0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
23fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23fe0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
23ff0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
24000 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
24010 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
24020 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
24030 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
24040 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
24050 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
24060 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
24070 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
24080 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
24090 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
240a0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
240b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
240c0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
240d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
240e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
240f0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
24100 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
24110 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
24120 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
24130 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
24140 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
24150 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
24160 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
24170 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
24180 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
24190 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
241a0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
241b0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
241c0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
241d0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
241e0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
241f0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
24200 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
24210 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
24220 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
24230 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
24240 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
24250 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
24260 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
24270 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
24280 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
24290 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
242a0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
242b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
242c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
242d0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
242e0 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
242f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
24300 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
24310 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24320 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
24330 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
24340 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
24350 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
24360 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
24370 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
24380 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
24390 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
243a0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
243b0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
243c0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
243d0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
243e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
243f0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
24400 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
24410 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
24420 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
24430 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
24440 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
24450 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
24460 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
24470 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
24480 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
24490 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
244a0 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
244b0 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
244c0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
244d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
244e0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
244f0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
24500 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
24510 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
24520 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
24530 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
24540 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
24550 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
24560 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
24570 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
24580 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24590 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
245a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
245b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
245c0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
245d0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
245e0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
245f0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
24600 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
24610 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
24620 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
24630 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
24640 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
24650 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
24660 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
24670 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
24680 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
24690 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
246a0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
246b0 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
246c0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
246d0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
246e0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
246f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
24700 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
24710 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
24720 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
24730 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
24740 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
24750 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
24760 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
24770 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
24780 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
24790 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
247a0 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
247b0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
247c0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
247d0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
247e0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
247f0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
24800 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
24810 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
24820 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
24830 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
24840 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
24850 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
24860 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
24870 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
24880 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
24890 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
248a0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
248b0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
248c0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
248d0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
248e0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
248f0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
24900 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
24910 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
24920 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
24930 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
24940 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
24950 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
24960 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
24970 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
24980 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
24990 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
249a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
249b0 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
249c0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
249d0 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65  then that parame
249e0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
249f0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
24a00 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
24a10 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
24a20 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
24a30 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
24a40 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
24a50 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
24a60 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
24a70 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
24a80 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
24a90 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
24aa0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
24ab0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
24ac0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
24ad0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
24ae0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
24af0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
24b00 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
24b10 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
24b20 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
24b30 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
24b40 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
24b50 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
24b60 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
24b70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24b80 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
24b90 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
24ba0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
24bb0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
24bc0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
24bd0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
24be0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
24bf0 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
24c00 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
24c10 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
24c20 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
24c30 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
24c40 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
24c50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
24c60 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
24c70 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
24c80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
24c90 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
24ca0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
24cb0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
24cc0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
24cd0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
24ce0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
24cf0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
24d00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
24d10 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
24d20 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
24d30 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
24d40 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
24d50 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
24d60 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
24d70 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
24d80 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
24d90 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
24da0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
24db0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
24dc0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
24dd0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
24de0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
24df0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
24e00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
24e10 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
24e20 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
24e30 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
24e40 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
24e50 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
24e60 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
24e70 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
24e80 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
24e90 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
24ea0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
24eb0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
24ec0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
24ed0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
24ee0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
24ef0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
24f00 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
24f10 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
24f20 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
24f30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
24f40 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
24f50 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
24f60 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
24f70 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
24f80 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
24f90 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
24fa0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
24fb0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
24fc0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
24fd0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
24fe0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
24ff0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
25000 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
25010 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
25020 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
25030 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
25040 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
25050 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
25060 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
25070 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
25080 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
25090 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
250a0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
250b0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
250c0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
250d0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
250e0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
250f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
25100 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
25110 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
25120 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
25130 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
25140 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
25150 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
25160 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
25170 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
25180 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
25190 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
251a0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
251b0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
251c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
251d0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
251e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
251f0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
25200 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
25210 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
25220 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
25230 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
25240 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
25250 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
25260 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
25270 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
25280 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
25290 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
252a0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
252b0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
252c0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
252d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
252e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
252f0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
25300 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25310 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
25320 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
25330 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
25340 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
25350 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
25360 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
25370 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25380 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
25390 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
253a0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
253b0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
253c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
253d0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
253e0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
253f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
25400 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
25410 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25420 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
25430 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
25440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
25450 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25460 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
25470 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
25480 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
25490 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
254a0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
254b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
254c0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
254d0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
254e0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
254f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
25500 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
25510 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
25520 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
25530 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
25540 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
25550 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25560 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
25570 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
25580 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
25590 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
255a0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
255b0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
255c0 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
255d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
255e0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
255f0 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
25600 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
25610 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
25620 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
25630 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
25640 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
25650 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
25660 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
25670 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
25680 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
25690 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
256a0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
256b0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
256c0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
256d0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
256e0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
256f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
25700 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
25710 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
25720 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
25730 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
25740 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
25750 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
25760 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
25770 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
25780 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
25790 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
257a0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
257b0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
257c0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
257d0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
257e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
257f0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
25800 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
25810 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
25820 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
25830 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
25840 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
25850 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
25860 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
25870 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
25880 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
25890 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
258a0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
258b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
258c0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
258d0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
258e0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
258f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25900 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
25910 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
25920 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
25930 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
25940 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
25950 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
25960 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
25970 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
25980 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
25990 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
259a0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
259b0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
259c0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
259d0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
259e0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
259f0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
25a00 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
25a10 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
25a20 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
25a30 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
25a40 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
25a50 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
25a60 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
25a70 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
25a80 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
25a90 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
25aa0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
25ab0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
25ac0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
25ad0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
25ae0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
25af0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
25b00 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
25b10 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
25b20 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
25b30 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
25b40 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
25b50 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
25b60 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
25b70 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
25b80 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
25b90 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
25ba0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
25bb0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
25bc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25bd0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
25be0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
25bf0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
25c00 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
25c10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
25c20 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
25c30 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
25c40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25c50 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
25c60 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25c70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25c80 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
25c90 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
25ca0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
25cb0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
25cc0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
25cd0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
25ce0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
25cf0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
25d00 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
25d10 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
25d20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
25d30 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
25d40 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
25d50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
25d60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25d70 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
25d80 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
25d90 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
25da0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
25db0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
25dc0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
25dd0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
25de0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
25df0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
25e00 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
25e10 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
25e20 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
25e30 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
25e40 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
25e50 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25e60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25e70 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
25e80 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
25e90 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
25ea0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
25eb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25ec0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
25ed0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
25ee0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
25ef0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
25f00 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
25f10 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
25f20 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
25f30 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
25f40 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25f50 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  ent.**.** ^Contr
25f60 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
25f70 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
25f80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
25f90 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
25fa0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
25fb0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
25fc0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
25fd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
25fe0 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
25ff0 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
26000 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
26010 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
26020 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
26030 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
26040 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
26050 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
26060 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
26070 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
26080 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
26090 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
260a0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
260b0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
260c0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
260d0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
260e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
260f0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
26100 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
26110 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
26120 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
26130 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
26140 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
26150 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
26160 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
26170 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
26180 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
26190 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
261a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
261b0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
261c0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
261d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
261e0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
261f0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
26200 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
26210 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
26220 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
26230 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
26240 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
26250 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
26260 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
26270 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
26280 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
26290 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
262a0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
262b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
262c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
262d0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
262e0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
262f0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
26300 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
26310 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26320 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
26330 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
26340 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
26350 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
26360 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
26370 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
26380 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
26390 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
263a0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
263b0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
263c0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
263d0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
263e0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
263f0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
26400 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
26410 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
26420 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
26430 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
26440 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
26450 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
26460 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
26470 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
26480 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
26490 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
264a0 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
264b0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
264c0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
264d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
264e0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
264f0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
26500 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
26510 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
26520 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
26530 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
26540 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
26550 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
26560 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
26570 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
26580 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
26590 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
265a0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
265b0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
265c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
265d0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
265e0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
265f0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
26600 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
26610 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
26620 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
26630 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26640 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
26650 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
26660 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
26670 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
26680 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
26690 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
266a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
266b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
266c0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
266d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
266e0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
266f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26700 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
26710 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
26720 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
26730 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
26740 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
26750 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
26760 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
26770 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
26780 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
26790 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
267a0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
267b0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
267c0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
267d0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
267e0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
267f0 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
26800 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
26810 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
26820 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
26830 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
26840 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
26850 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
26860 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
26870 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
26880 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
26890 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
268a0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
268b0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
268c0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
268d0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
268e0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
268f0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
26900 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
26910 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
26920 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
26930 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26940 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
26950 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
26960 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
26970 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
26980 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
26990 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
269a0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
269b0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
269c0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
269d0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
269e0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
269f0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
26a00 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
26a10 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
26a20 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
26a30 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
26a40 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
26a50 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
26a60 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
26a70 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
26a80 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
26a90 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
26aa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26ab0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
26ac0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
26ad0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
26ae0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
26af0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
26b00 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
26b10 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
26b20 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
26b30 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
26b40 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
26b50 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
26b60 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
26b70 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
26b80 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
26b90 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
26ba0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
26bb0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
26bc0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
26bd0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
26be0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
26bf0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
26c00 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
26c10 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
26c20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
26c30 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
26c40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
26c50 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
26c60 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
26c70 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
26c80 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
26c90 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
26ca0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
26cb0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
26cc0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
26cd0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
26ce0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
26cf0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
26d00 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
26d10 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
26d20 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
26d30 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
26d40 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
26d50 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
26d60 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
26d70 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
26d80 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
26d90 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
26da0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
26db0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
26dc0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
26dd0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
26de0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
26df0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
26e00 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
26e10 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
26e20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
26e30 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
26e40 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26e50 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
26e60 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
26e70 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
26e80 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
26e90 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
26ea0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
26eb0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
26ec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
26ed0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
26ee0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
26ef0 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
26f00 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
26f10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26f20 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
26f30 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
26f40 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
26f50 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
26f60 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
26f70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
26f80 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
26f90 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
26fa0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
26fb0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
26fc0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
26fd0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
26fe0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
26ff0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
27000 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
27010 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
27020 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
27030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27040 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
27050 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
27060 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
27070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
27080 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
27090 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
270a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
270b0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
270c0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
270d0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
270e0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
270f0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
27100 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
27110 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
27120 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
27130 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27140 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
27150 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
27160 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
27170 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
27180 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
27190 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
271a0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
271b0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
271c0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
271d0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
271e0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
271f0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
27200 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
27210 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
27220 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
27230 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
27240 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
27250 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
27260 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
27270 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
27280 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
27290 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
272a0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
272b0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
272c0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
272d0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
272e0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
272f0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
27300 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
27310 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
27320 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
27330 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
27340 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
27350 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
27360 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
27370 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
27380 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
27390 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
273a0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
273b0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
273c0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
273d0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
273e0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
273f0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
27400 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
27410 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
27420 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
27430 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
27440 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
27450 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
27460 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
27470 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
27480 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
27490 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
274a0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
274b0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
274c0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
274d0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
274e0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
274f0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
27500 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
27510 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
27520 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
27530 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
27540 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
27550 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
27560 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
27570 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
27580 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
27590 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
275a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
275b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
275c0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
275d0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
275e0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
275f0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
27600 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
27610 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27620 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
27630 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
27640 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
27650 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27660 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
27670 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
27680 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
27690 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
276a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
276b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
276c0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
276d0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
276e0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
276f0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
27700 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
27710 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
27720 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
27730 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
27740 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
27750 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
27760 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
27770 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
27780 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
27790 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
277a0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
277b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
277c0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
277d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
277e0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
277f0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
27800 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
27810 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
27820 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
27830 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
27840 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
27850 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
27860 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
27870 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
27880 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
27890 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
278a0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
278b0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
278c0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
278d0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
278e0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
278f0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
27900 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
27910 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
27920 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
27930 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
27940 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
27950 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
27960 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
27970 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
27980 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
27990 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
279a0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
279b0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
279c0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
279d0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
279e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
279f0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
27a00 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
27a10 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
27a20 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
27a30 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
27a40 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
27a50 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
27a60 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
27a70 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
27a80 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
27a90 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
27aa0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
27ab0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
27ac0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
27ad0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
27ae0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
27af0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
27b00 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
27b10 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
27b20 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
27b30 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
27b40 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
27b50 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
27b60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
27b70 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
27b80 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
27b90 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
27ba0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
27bb0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
27bc0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
27bd0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
27be0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
27bf0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
27c00 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
27c10 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
27c20 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
27c30 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
27c40 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
27c50 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
27c60 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
27c70 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
27c80 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
27c90 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
27ca0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
27cb0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
27cc0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
27cd0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
27ce0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
27cf0 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
27d00 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
27d10 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
27d20 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
27d30 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
27d40 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
27d50 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
27d60 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
27d70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
27d80 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
27d90 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
27da0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
27db0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
27dc0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
27dd0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
27de0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
27df0 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
27e00 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
27e10 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
27e20 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
27e30 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
27e40 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
27e50 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
27e60 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
27e70 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
27e80 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
27e90 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
27ea0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
27eb0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
27ec0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
27ed0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
27ee0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
27ef0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27f00 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
27f10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
27f20 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
27f30 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
27f40 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
27f50 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
27f60 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
27f70 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
27f80 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
27f90 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
27fa0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
27fb0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
27fc0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
27fd0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
27fe0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
27ff0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28000 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
28010 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
28020 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
28030 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
28040 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
28050 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
28060 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
28070 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
28080 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
28090 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
280a0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
280b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
280c0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
280d0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
280e0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
280f0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
28100 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
28110 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
28120 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
28130 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
28140 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
28150 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
28160 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
28170 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
28180 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
28190 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
281a0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
281b0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
281c0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
281d0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
281e0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
281f0 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
28200 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28210 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
28220 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28230 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
28240 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
28250 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
28260 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
28270 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
28280 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
28290 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
282a0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
282b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
282c0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
282d0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
282e0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
282f0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
28300 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
28310 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
28320 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
28330 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
28340 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
28350 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
28360 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
28370 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
28380 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
28390 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
283a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
283b0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
283c0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
283d0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
283e0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
283f0 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
28400 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
28410 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
28420 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
28430 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
28440 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
28450 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
28460 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
28470 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
28480 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
28490 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
284a0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
284b0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
284c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
284d0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
284e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
284f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
28500 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
28510 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
28520 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
28530 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
28540 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
28550 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
28560 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
28570 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
28580 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
28590 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
285a0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
285b0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
285c0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
285d0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
285e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
285f0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
28600 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28610 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
28620 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
28630 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
28640 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
28650 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
28660 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
28670 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
28680 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
28690 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
286a0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
286b0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
286c0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
286d0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
286e0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
286f0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
28700 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
28710 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
28720 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
28730 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
28740 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
28750 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
28760 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28770 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
28780 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28790 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
287a0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
287b0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
287c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
287d0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
287e0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
287f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28800 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
28810 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
28820 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
28830 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
28840 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28850 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
28860 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
28870 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
28880 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
28890 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
288a0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
288b0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
288c0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
288d0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
288e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
288f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28900 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
28910 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
28920 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
28930 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
28940 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
28950 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
28960 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
28970 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
28980 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
28990 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
289a0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
289b0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
289c0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
289d0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
289e0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
289f0 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
28a00 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
28a10 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
28a20 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
28a30 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
28a40 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
28a50 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
28a60 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
28a70 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
28a80 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28a90 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
28aa0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
28ab0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
28ac0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
28ad0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28ae0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
28af0 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
28b00 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
28b10 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
28b20 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
28b30 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
28b40 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
28b50 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
28b60 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
28b70 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
28b80 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
28b90 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
28ba0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
28bb0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
28bc0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
28bd0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
28be0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
28bf0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
28c00 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
28c10 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
28c20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
28c30 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
28c40 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
28c50 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
28c60 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
28c70 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
28c80 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
28c90 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
28ca0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
28cb0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
28cc0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
28cd0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
28ce0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
28cf0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
28d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
28d10 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
28d20 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
28d30 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
28d40 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
28d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
28d60 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
28d70 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
28d80 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
28d90 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
28da0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
28db0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
28dc0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
28dd0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
28de0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
28df0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
28e00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
28e10 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
28e20 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
28e30 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
28e40 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
28e50 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
28e60 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
28e70 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
28e80 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
28e90 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
28ea0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
28eb0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
28ec0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
28ed0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
28ee0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
28ef0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
28f00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28f10 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
28f20 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
28f30 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
28f40 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
28f50 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
28f60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28f70 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
28f80 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
28f90 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
28fa0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
28fb0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
28fc0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
28fd0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
28fe0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
28ff0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
29000 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
29010 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
29020 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
29030 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
29040 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
29050 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
29060 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
29070 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
29080 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
29090 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
290a0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
290b0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
290c0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
290d0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
290e0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
290f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
29100 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
29110 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
29120 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
29130 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
29140 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
29150 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29160 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
29170 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
29180 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
29190 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
291a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
291b0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
291c0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
291d0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
291e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
291f0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
29200 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29210 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
29220 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
29230 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
29240 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
29250 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
29260 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
29270 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
29280 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
29290 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
292a0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
292b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
292c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
292d0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
292e0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
292f0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
29300 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
29310 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
29320 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
29330 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
29340 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
29350 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
29360 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
29370 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
29380 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
29390 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
293a0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
293b0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
293c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
293d0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
293e0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
293f0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
29400 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
29410 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
29420 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
29430 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
29440 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
29450 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
29460 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
29470 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
29480 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
29490 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
294a0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
294b0 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
294c0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
294d0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
294e0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
294f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
29500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
29510 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
29520 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
29530 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
29540 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
29550 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
29560 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
29570 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
29580 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
29590 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
295a0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
295b0 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
295c0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
295d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
295e0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
295f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
29600 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
29610 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
29620 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
29630 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
29640 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
29650 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
29660 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
29670 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
29680 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
29690 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
296a0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
296b0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
296c0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
296d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
296e0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
296f0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
29700 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
29710 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
29720 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
29730 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
29740 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
29750 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
29760 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
29770 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
29780 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29790 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
297a0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
297b0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
297c0 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
297d0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
297e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
297f0 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
29800 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
29810 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
29820 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
29830 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
29840 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
29850 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
29860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29870 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
29880 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
29890 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
298a0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
298b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
298c0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
298d0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
298e0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
298f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
29900 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
29910 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
29920 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
29930 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
29940 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
29950 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
29960 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
29970 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
29980 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
29990 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
299a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
299b0 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
299c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
299d0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
299e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
299f0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
29a00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29a10 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
29a20 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
29a30 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
29a40 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
29a50 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
29a60 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
29a70 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
29a80 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
29a90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
29aa0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
29ab0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
29ac0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
29ad0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
29ae0 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
29af0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
29b00 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
29b10 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
29b20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29b30 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
29b40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29b50 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
29b60 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
29b70 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
29b80 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
29b90 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
29ba0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
29bb0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
29bc0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
29bd0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29be0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
29bf0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
29c00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29c10 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
29c20 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
29c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
29c40 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
29c50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29c60 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
29c70 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
29c80 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
29c90 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
29ca0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
29cb0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
29cc0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
29cd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
29ce0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
29cf0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
29d00 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
29d10 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
29d20 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
29d30 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
29d40 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
29d50 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
29d60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
29d70 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
29d80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
29d90 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
29da0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
29db0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
29dc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
29dd0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
29de0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
29df0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
29e00 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
29e10 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
29e20 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
29e30 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
29e40 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
29e50 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
29e60 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
29e70 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
29e80 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
29e90 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
29ea0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
29eb0 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
29ec0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
29ed0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
29ee0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
29ef0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
29f00 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
29f10 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
29f20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
29f30 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
29f40 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
29f50 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
29f60 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
29f70 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
29f80 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
29f90 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
29fa0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
29fb0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
29fc0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
29fd0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
29fe0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
29ff0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2a000 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2a010 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2a020 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2a030 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2a040 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2a050 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2a060 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2a070 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2a080 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2a090 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2a0a0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2a0b0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2a0c0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2a0d0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2a0e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2a0f0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2a100 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2a110 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2a120 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2a130 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2a140 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2a150 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
2a160 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2a170 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2a180 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2a190 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2a1a0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
2a1b0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2a1c0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2a1d0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
2a1e0 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
2a1f0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2a200 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2a210 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
2a220 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2a230 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2a240 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
2a250 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2a260 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
2a270 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
2a280 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
2a290 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
2a2a0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
2a2b0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
2a2c0 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
2a2d0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2a2e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2a2f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2a300 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2a310 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
2a320 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2a330 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2a340 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
2a350 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
2a360 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2a370 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
2a380 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
2a390 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
2a3a0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
2a3b0 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
2a3c0 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
2a3d0 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
2a3e0 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
2a3f0 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
2a400 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
2a410 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
2a420 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
2a430 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
2a440 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
2a450 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
2a460 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
2a470 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
2a480 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
2a490 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
2a4a0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
2a4b0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2a4c0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
2a4d0 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
2a4e0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2a4f0 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
2a500 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2a510 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
2a520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a530 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
2a540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a550 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
2a560 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
2a570 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
2a580 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
2a590 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
2a5a0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
2a5b0 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
2a5c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2a5d0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2a5e0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
2a5f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2a600 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
2a610 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2a620 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2a630 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
2a640 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
2a650 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
2a660 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
2a670 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
2a680 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2a690 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2a6a0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
2a6b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a6c0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
2a6d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a6e0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2a6f0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2a700 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2a710 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2a720 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
2a730 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2a740 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
2a750 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2a760 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2a770 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2a780 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2a790 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2a7a0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2a7b0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2a7c0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
2a7d0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2a7e0 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
2a7f0 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
2a800 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
2a810 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
2a820 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
2a830 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
2a840 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
2a850 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
2a860 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2a870 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
2a880 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
2a890 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
2a8a0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
2a8b0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
2a8c0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
2a8d0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
2a8e0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
2a8f0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
2a900 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
2a910 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
2a920 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
2a930 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
2a940 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
2a950 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
2a960 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
2a970 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
2a980 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
2a990 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
2a9a0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
2a9b0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
2a9c0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
2a9d0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2a9e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
2a9f0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2aa00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2aa10 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2aa20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2aa30 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2aa40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2aa50 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2aa60 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2aa70 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
2aa80 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2aa90 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
2aaa0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
2aab0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2aac0 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
2aad0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
2aae0 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
2aaf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2ab00 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
2ab10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2ab20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
2ab30 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
2ab40 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
2ab50 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
2ab60 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2ab70 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
2ab80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ab90 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
2aba0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
2abb0 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
2abc0 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
2abd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2abe0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2abf0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
2ac00 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
2ac10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ac20 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
2ac30 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
2ac40 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2ac50 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
2ac60 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
2ac70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ac80 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
2ac90 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2aca0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
2acb0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2acc0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
2acd0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
2ace0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
2acf0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2ad00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2ad10 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2ad20 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
2ad30 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
2ad40 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
2ad50 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
2ad60 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
2ad70 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
2ad80 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
2ad90 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
2ada0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
2adb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2adc0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2add0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2ade0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2adf0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2ae00 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2ae10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2ae20 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2ae30 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2ae40 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2ae50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2ae60 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2ae70 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2ae80 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2ae90 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2aea0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2aeb0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2aec0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2aed0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2aee0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2aef0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2af00 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2af10 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2af20 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
2af30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2af40 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2af50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2af60 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2af70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2af80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2af90 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2afa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2afb0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2afc0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
2afd0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2afe0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2aff0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2b000 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2b010 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
2b020 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2b030 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
2b040 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
2b050 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
2b060 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2b070 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
2b080 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2b090 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
2b0a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2b0b0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
2b0c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b0d0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
2b0e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2b0f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2b100 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
2b110 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2b120 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
2b130 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2b140 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2b150 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2b160 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b170 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2b180 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2b190 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2b1a0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2b1b0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2b1c0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2b1d0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2b1e0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2b1f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2b200 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2b210 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2b220 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2b230 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2b240 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2b250 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2b260 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2b270 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2b280 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2b290 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2b2a0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2b2b0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2b2c0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2b2d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2b2e0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2b2f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2b300 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2b310 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2b320 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2b330 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2b340 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2b350 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2b360 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2b370 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2b380 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2b390 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2b3a0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2b3b0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2b3c0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2b3d0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2b3e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2b3f0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2b400 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2b410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2b420 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2b430 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2b440 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2b450 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2b460 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2b470 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2b480 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2b490 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2b4a0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2b4b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2b4c0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2b4d0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2b4e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b4f0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2b500 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2b510 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2b520 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2b530 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b540 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2b550 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2b560 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2b570 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2b580 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2b590 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2b5a0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2b5b0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2b5c0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2b5d0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2b5e0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2b5f0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2b600 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
2b610 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
2b620 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2b630 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2b640 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2b660 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2b670 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2b680 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2b690 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
2b6a0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2b6b0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
2b6c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2b6d0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
2b6e0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2b6f0 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
2b700 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
2b710 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
2b720 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
2b730 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
2b740 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
2b750 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2b760 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2b770 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
2b780 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
2b790 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
2b7a0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2b7b0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
2b7c0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
2b7d0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2b7e0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2b7f0 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
2b800 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b810 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
2b820 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
2b830 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
2b840 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2b850 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2b860 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2b870 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2b880 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b890 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
2b8a0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
2b8b0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
2b8c0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
2b8d0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2b8e0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2b8f0 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
2b900 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
2b910 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2b920 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
2b930 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2b940 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2b950 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2b960 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2b970 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b980 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
2b990 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
2b9a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b9b0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
2b9c0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2b9d0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2b9e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2b9f0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2ba00 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2ba10 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
2ba20 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2ba30 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2ba40 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2ba50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2ba60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ba70 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2ba80 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2ba90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2baa0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2bab0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
2bac0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
2bad0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2bae0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
2baf0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2bb00 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2bb10 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
2bb20 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2bb30 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2bb40 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
2bb50 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2bb60 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
2bb70 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
2bb80 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2bb90 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
2bba0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
2bbb0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2bbc0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
2bbd0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
2bbe0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
2bbf0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2bc00 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
2bc10 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
2bc20 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
2bc30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2bc40 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2bc50 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
2bc60 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
2bc70 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
2bc80 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2bc90 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
2bca0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
2bcb0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
2bcc0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
2bcd0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
2bce0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2bcf0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
2bd00 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
2bd10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2bd20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bd30 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
2bd40 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
2bd50 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
2bd60 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
2bd70 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
2bd80 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
2bd90 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2bda0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
2bdb0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2bdc0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
2bdd0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
2bde0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bdf0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
2be00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2be10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2be20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
2be30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
2be40 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
2be50 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
2be60 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
2be70 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
2be80 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
2be90 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
2bea0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
2beb0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
2bec0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
2bed0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
2bee0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
2bef0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
2bf00 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
2bf10 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
2bf20 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
2bf30 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
2bf40 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
2bf50 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
2bf60 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
2bf70 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2bf80 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
2bf90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2bfa0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
2bfb0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
2bfc0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2bfd0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
2bfe0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2bff0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
2c000 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
2c010 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
2c020 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2c030 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
2c040 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
2c050 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
2c060 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
2c070 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
2c080 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2c090 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
2c0a0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
2c0b0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
2c0c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
2c0d0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
2c0e0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
2c0f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2c100 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
2c110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
2c120 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
2c130 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
2c140 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
2c150 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
2c160 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
2c170 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
2c180 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
2c190 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
2c1a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2c1b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2c1c0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
2c1d0 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
2c1e0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
2c1f0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
2c200 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2c210 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
2c220 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
2c230 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
2c240 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
2c250 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
2c260 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
2c270 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c280 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
2c290 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2c2a0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
2c2b0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
2c2c0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
2c2d0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
2c2e0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
2c2f0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
2c300 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2c310 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2c320 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
2c330 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
2c340 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
2c350 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
2c360 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
2c370 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
2c380 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
2c390 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
2c3a0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
2c3b0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
2c3c0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
2c3d0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
2c3e0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
2c3f0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
2c400 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
2c410 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
2c420 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
2c430 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
2c440 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
2c450 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2c460 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
2c470 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
2c480 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
2c490 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
2c4a0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
2c4b0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
2c4c0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
2c4d0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
2c4e0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
2c4f0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
2c500 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
2c510 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
2c520 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
2c530 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2c540 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2c550 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
2c560 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2c570 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2c580 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
2c590 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
2c5a0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
2c5b0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
2c5c0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
2c5d0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
2c5e0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
2c5f0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2c600 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2c610 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2c620 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
2c630 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
2c640 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
2c650 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
2c660 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
2c670 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
2c680 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2c690 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
2c6a0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
2c6b0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
2c6c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
2c6d0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
2c6e0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
2c6f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c700 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
2c710 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
2c720 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
2c730 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
2c740 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2c750 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
2c760 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
2c770 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
2c780 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
2c790 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
2c7a0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
2c7b0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
2c7c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c7d0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
2c7e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2c7f0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
2c800 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
2c810 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c820 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
2c830 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
2c840 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2c850 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
2c860 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
2c870 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
2c880 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
2c890 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
2c8a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2c8b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2c8c0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
2c8d0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
2c8e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2c8f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c900 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
2c910 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
2c920 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
2c930 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2c940 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2c950 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
2c960 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
2c970 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
2c980 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
2c990 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
2c9a0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
2c9b0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
2c9c0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
2c9d0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
2c9e0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
2c9f0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
2ca00 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
2ca10 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
2ca20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
2ca30 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
2ca40 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2ca50 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
2ca60 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
2ca70 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
2ca80 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
2ca90 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
2caa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2cab0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
2cac0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
2cad0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2cae0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2caf0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
2cb00 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
2cb10 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
2cb20 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
2cb30 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2cb40 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2cb50 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
2cb60 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
2cb70 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2cb80 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2cb90 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
2cba0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
2cbb0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
2cbc0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2cbd0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2cbe0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
2cbf0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
2cc00 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
2cc10 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
2cc20 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
2cc30 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
2cc40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2cc50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
2cc60 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
2cc70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2cc80 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
2cc90 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
2cca0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
2ccb0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
2ccc0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
2ccd0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
2cce0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2ccf0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
2cd00 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
2cd10 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2cd20 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
2cd30 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2cd40 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
2cd50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2cd60 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
2cd70 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2cd80 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
2cd90 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2cda0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2cdb0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2cdc0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2cdd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2cde0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2cdf0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2ce00 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2ce10 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2ce20 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2ce30 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2ce40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2ce50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2ce60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2ce70 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2ce80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2ce90 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2cea0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2ceb0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2cec0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2ced0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2cee0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2cef0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2cf00 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2cf10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2cf20 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2cf30 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2cf40 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2cf50 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
2cf60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2cf70 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
2cf80 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2cf90 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
2cfa0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2cfb0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2cfc0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2cfd0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2cfe0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2cff0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2d000 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2d010 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2d020 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2d030 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2d040 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2d050 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d060 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
2d070 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
2d080 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d090 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
2d0a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2d0b0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
2d0c0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
2d0d0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
2d0e0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
2d0f0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
2d100 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
2d110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2d120 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
2d130 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2d140 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
2d150 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2d160 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
2d170 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2d180 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
2d190 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
2d1a0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
2d1b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
2d1c0 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
2d1d0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
2d1e0 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
2d1f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2d200 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2d210 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
2d220 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2d230 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
2d240 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
2d250 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
2d260 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
2d270 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2d280 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
2d290 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
2d2a0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
2d2b0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2d2c0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
2d2d0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
2d2e0 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
2d2f0 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
2d300 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
2d310 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2d320 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
2d330 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
2d340 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
2d350 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
2d360 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
2d370 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
2d380 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
2d390 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
2d3a0 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
2d3b0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
2d3c0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
2d3d0 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
2d3e0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2d3f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2d400 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
2d410 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
2d420 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2d430 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
2d440 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
2d450 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2d460 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
2d470 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
2d480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
2d490 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
2d4a0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2d4b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
2d4c0 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
2d4d0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2d4e0 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
2d4f0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
2d500 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
2d510 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2d520 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
2d530 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
2d540 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
2d550 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
2d560 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
2d570 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d580 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
2d590 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
2d5a0 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
2d5b0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
2d5c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2d5d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
2d5e0 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
2d5f0 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
2d600 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
2d610 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
2d620 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
2d630 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
2d640 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2d650 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
2d660 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
2d670 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
2d680 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
2d690 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
2d6a0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
2d6b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2d6c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2d6d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2d6e0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
2d6f0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
2d700 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2d710 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2d720 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
2d730 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2d740 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
2d750 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
2d760 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
2d770 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d780 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2d790 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
2d7a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2d7b0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
2d7c0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
2d7d0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2d7e0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2d7f0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
2d800 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
2d810 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2d820 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2d830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2d840 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
2d850 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
2d860 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d870 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
2d880 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
2d890 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2d8a0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
2d8b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
2d8c0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
2d8d0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
2d8e0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
2d8f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2d900 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
2d910 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2d920 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2d930 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
2d940 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
2d950 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
2d960 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
2d970 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d980 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
2d990 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
2d9a0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
2d9b0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
2d9c0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
2d9d0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
2d9e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2d9f0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
2da00 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
2da10 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
2da20 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2da30 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
2da40 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
2da50 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
2da60 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
2da70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
2da80 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
2da90 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
2daa0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
2dab0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
2dac0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
2dad0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2dae0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
2daf0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2db00 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
2db10 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
2db20 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
2db30 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
2db40 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
2db50 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
2db60 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
2db70 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2db80 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
2db90 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
2dba0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
2dbb0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
2dbc0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
2dbd0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
2dbe0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
2dbf0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
2dc00 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
2dc10 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
2dc20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
2dc30 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
2dc40 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
2dc50 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
2dc60 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
2dc70 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
2dc80 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2dc90 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
2dca0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
2dcb0 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
2dcc0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
2dcd0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
2dce0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
2dcf0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
2dd00 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2dd10 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
2dd20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2dd30 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
2dd40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2dd50 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
2dd60 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
2dd70 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
2dd80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2dd90 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
2dda0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2ddb0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
2ddc0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2ddd0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2dde0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
2ddf0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2de00 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
2de10 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2de20 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
2de30 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2de40 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
2de50 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2de60 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
2de70 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
2de80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2de90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2dea0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2deb0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
2dec0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2ded0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2dee0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
2def0 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
2df00 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2df10 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2df20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2df30 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
2df40 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
2df50 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2df60 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
2df70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2df80 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2df90 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2dfa0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
2dfb0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2dfc0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2dfd0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
2dfe0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2dff0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2e000 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
2e010 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2e020 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2e030 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
2e040 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e050 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2e060 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
2e070 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2e080 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
2e090 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
2e0a0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
2e0b0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
2e0c0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
2e0d0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
2e0e0 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
2e0f0 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
2e100 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
2e110 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
2e120 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
2e130 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
2e140 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
2e150 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
2e160 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
2e170 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2e180 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
2e190 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
2e1a0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
2e1b0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
2e1c0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
2e1d0 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
2e1e0 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
2e1f0 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
2e200 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
2e210 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
2e220 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
2e230 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
2e240 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2e250 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2e260 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
2e270 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
2e280 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
2e290 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
2e2a0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
2e2b0 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
2e2c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
2e2d0 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
2e2e0 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
2e2f0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
2e300 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
2e310 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
2e320 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
2e330 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
2e340 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2e350 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
2e360 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
2e370 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
2e380 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
2e390 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
2e3a0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
2e3b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e3c0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
2e3d0 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
2e3e0 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
2e3f0 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
2e400 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
2e410 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2e420 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
2e430 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
2e440 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
2e450 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
2e460 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
2e470 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2e480 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
2e490 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
2e4a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20  LL pointer if N 
2e4b0 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
2e4c0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
2e4d0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
2e4e0 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
2e4f0 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
2e500 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
2e510 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
2e520 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2e530 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
2e540 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
2e550 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
2e560 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
2e570 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
2e580 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
2e590 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
2e5a0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
2e5b0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2e5c0 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
2e5d0 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
2e5e0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2e5f0 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
2e600 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
2e610 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
2e620 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  on.)^.**.** ^SQL
2e630 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
2e640 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
2e650 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
2e660 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
2e670 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2e680 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
2e690 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
2e6a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
2e6b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
2e6c0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
2e6d0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2e6e0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
2e6f0 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
2e700 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
2e710 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
2e720 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
2e730 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
2e740 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
2e750 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
2e760 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
2e770 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
2e780 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
2e790 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2e7a0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2e7b0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
2e7c0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2e7d0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
2e7e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
2e7f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
2e800 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e810 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
2e820 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
2e830 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
2e840 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
2e850 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2e860 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2e870 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2e880 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2e890 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2e8a0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2e8b0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2e8c0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2e8d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e8e0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2e8f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2e900 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2e910 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2e920 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2e930 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2e940 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2e950 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2e960 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2e970 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2e980 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2e990 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2e9a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2e9b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2e9c0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2e9d0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
2e9e0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2e9f0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
2ea00 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2ea10 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
2ea20 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
2ea30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2ea40 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2ea50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2ea60 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2ea70 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
2ea80 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2ea90 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
2eaa0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
2eab0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2eac0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ead0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2eae0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2eaf0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2eb00 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2eb10 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2eb20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2eb30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2eb40 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
2eb50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2eb60 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
2eb70 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
2eb80 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
2eb90 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
2eba0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ata.**.** The fo
2ebb0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
2ebc0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
2ebd0 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
2ebe0 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
2ebf0 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
2ec00 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
2ec10 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
2ec20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
2ec30 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
2ec40 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
2ec50 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
2ec60 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
2ec70 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
2ec80 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
2ec90 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
2eca0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
2ecb0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
2ecc0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
2ecd0 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
2ece0 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
2ecf0 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
2ed00 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
2ed10 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
2ed20 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
2ed30 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
2ed40 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2ed50 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
2ed60 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2ed70 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
2ed80 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
2ed90 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
2eda0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
2edb0 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
2edc0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
2edd0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
2ede0 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
2edf0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
2ee00 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2ee10 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
2ee20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
2ee30 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
2ee40 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
2ee50 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
2ee60 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
2ee70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ee80 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
2ee90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2eea0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2eeb0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
2eec0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
2eed0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2eee0 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
2eef0 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
2ef00 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
2ef10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ef20 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2ef30 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61  n. ^If no metada
2ef40 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72  ta has been ever
2ef50 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72  .** been set for
2ef60 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
2ef70 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  t of the functio
2ef80 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72  n, or if the cor
2ef90 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75  responding.** fu
2efa0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2efb0 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e   has changed sin
2efc0 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ce the meta-data
2efd0 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65   was set,.** the
2efe0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
2eff0 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20  xdata() returns 
2f000 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2f010 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f020 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2f030 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
2f040 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
2f050 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
2f060 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
2f070 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
2f080 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
2f090 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2f0a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f0b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
2f0c0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
2f0d0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
2f0e0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
2f0f0 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
2f100 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
2f110 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
2f120 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  oyed..** ^If it 
2f130 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
2f140 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
2f150 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
2f160 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
2f170 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
2f180 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2f190 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
2f1a0 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74  n.** the metadat
2f1b0 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
2f1c0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
2f1d0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
2f1e0 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
2f1f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2f200 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
2f210 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
2f220 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
2f230 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
2f240 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
2f250 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61  nd drop metadata
2f260 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d   on any.** param
2f270 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63  eter of any func
2f280 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65  tion at any time
2f290 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61  .  ^The only gua
2f2a0 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
2f2b0 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
2f2c0 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
2f2d0 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
2f2e0 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
2f2f0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
2f300 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
2f310 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
2f320 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
2f330 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
2f340 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
2f350 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
2f360 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
2f370 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
2f380 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
2f390 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a  ameters].)^.**.*
2f3a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2f3b0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2f3c0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2f3d0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2f3e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2f3f0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
2f400 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
2f410 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
2f420 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2f430 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
2f440 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
2f450 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2f460 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
2f470 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
2f480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f490 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
2f4a0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
2f4b0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
2f4c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
2f4d0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
2f4e0 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
2f4f0 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
2f500 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
2f510 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
2f520 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2f530 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2f540 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
2f550 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
2f560 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
2f570 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
2f580 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
2f590 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
2f5a0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
2f5b0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
2f5c0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
2f5d0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
2f5e0 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
2f5f0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
2f600 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
2f610 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
2f620 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
2f630 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
2f640 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
2f650 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
2f660 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2f670 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2f680 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
2f690 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
2f6a0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
2f6b0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
2f6c0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
2f6d0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
2f6e0 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
2f6f0 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
2f700 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
2f710 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
2f720 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
2f730 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
2f740 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
2f750 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
2f760 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
2f770 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
2f780 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
2f790 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2f7a0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
2f7b0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
2f7c0 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
2f7d0 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
2f7e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2f7f0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
2f800 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
2f810 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
2f820 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
2f830 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2f840 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
2f850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2f860 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2f870 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2f880 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2f890 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
2f8a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2f8b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2f8c0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
2f8d0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
2f8e0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2f8f0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
2f900 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
2f910 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
2f920 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2f930 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
2f940 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
2f950 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
2f960 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
2f970 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2f980 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2f990 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2f9a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2f9b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2f9c0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
2f9d0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
2f9e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f9f0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
2fa00 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
2fa10 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
2fa20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
2fa30 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
2fa40 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
2fa50 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
2fa60 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
2fa70 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
2fa80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2fa90 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
2faa0 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
2fab0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
2fac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2fad0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2fae0 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
2faf0 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
2fb00 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
2fb10 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
2fb20 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
2fb30 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
2fb40 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
2fb50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2fb60 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
2fb70 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2fb80 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
2fb90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2fba0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2fbb0 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
2fbc0 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
2fbd0 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
2fbe0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
2fbf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2fc00 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2fc10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fc20 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
2fc30 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
2fc40 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
2fc50 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
2fc60 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
2fc70 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  ..** ^SQLite use
2fc80 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
2fc90 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
2fca0 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
2fcb0 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
2fcc0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
2fcd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2fce0 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
2fcf0 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
2fd00 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69   message.  ^SQLi
2fd10 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
2fd20 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
2fd30 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
2fd40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2fd50 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
2fd60 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72  ^SQLite.** inter
2fd70 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
2fd80 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2fd90 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
2fda0 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
2fdb0 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
2fdc0 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  .  ^If the third
2fdd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2fde0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fdf0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2fe00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2fe10 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
2fe20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
2fe30 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
2fe40 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
2fe50 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
2fe60 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
2fe70 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
2fe80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2fe90 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
2fea0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a  sult_error() or.
2feb0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2fec0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
2fed0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e  on-negative then
2fee0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
2fef0 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73  at many.** bytes
2ff00 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
2ff10 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  ) from the 2nd p
2ff20 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2ff30 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
2ff40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2ff50 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2ff60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2ff70 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
2ff80 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
2ff90 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2ffa0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2ffb0 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
2ffc0 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
2ffd0 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
2ffe0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
2fff0 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
30000 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
30010 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
30020 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
30030 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
30040 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
30050 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
30060 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
30070 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
30080 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
30090 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
300a0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
300b0 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20  ^By default,.** 
300c0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
300d0 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
300e0 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63   ^A subsequent c
300f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
30100 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
30110 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
30120 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
30130 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
30140 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
30150 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OR..**.** ^The s
30160 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f  qlite3_result_to
30170 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
30180 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
30190 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
301a0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
301b0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
301c0 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67  BLOB is too long
301d0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
301e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
301f0 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29  3_result_nomem()
30200 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
30210 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
30220 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
30230 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
30240 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
30250 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
30260 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
30270 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
30280 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
30290 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
302a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
302b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
302c0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
302d0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
302e0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
302f0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
30300 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
30310 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
30320 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
30330 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
30340 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
30350 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30360 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
30370 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
30380 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
30390 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
303a0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
303b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
303c0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
303d0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
303e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
303f0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
30400 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30410 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
30420 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
30430 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
30440 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
30450 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
30460 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30470 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
30480 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30490 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
304a0 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
304b0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
304c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
304d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
304e0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
304f0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
30500 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
30510 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
30520 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
30530 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
30540 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
30550 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
30560 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
30570 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
30580 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
30590 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
305a0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
305b0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
305c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
305d0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
305e0 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
305f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
30600 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
30610 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
30620 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
30630 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
30640 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
30650 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
30660 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
30670 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
30680 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
30690 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
306a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
306b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
306c0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
306d0 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
306e0 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
306f0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
30700 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
30710 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
30720 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
30730 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
30740 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
30750 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
30760 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
30770 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
30780 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
30790 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
307a0 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
307b0 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
307c0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
307d0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
307e0 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
307f0 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
30800 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
30810 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
30820 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
30830 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
30840 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
30850 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
30860 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
30870 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
30880 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
30890 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
308a0 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
308b0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
308c0 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
308d0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
308e0 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
308f0 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
30900 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
30910 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
30920 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
30930 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
30940 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
30950 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
30960 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
30970 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
30980 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
30990 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
309a0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
309b0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
309c0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
309d0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
309e0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
309f0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
30a00 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
30a10 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
30a20 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30a30 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
30a40 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
30a50 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
30a60 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
30a70 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
30a80 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
30a90 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
30aa0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
30ab0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
30ac0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
30ad0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
30ae0 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
30af0 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
30b00 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
30b10 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
30b20 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
30b30 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
30b40 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
30b50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
30b60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
30b70 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30b80 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
30b90 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
30ba0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
30bb0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
30bc0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
30bd0 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
30be0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
30bf0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
30c00 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
30c10 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
30c20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
30c30 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
30c40 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
30c50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30c60 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
30c70 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
30c80 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
30c90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30ca0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
30cb0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
30cc0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30cd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30ce0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
30cf0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
30d00 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
30d10 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
30d20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
30d30 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
30d40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
30d50 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
30d60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
30d70 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
30d80 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
30d90 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
30da0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
30db0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
30dc0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
30dd0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
30de0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30df0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30e00 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
30e10 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
30e20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
30e30 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30e40 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
30e50 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
30e60 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
30e70 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
30e80 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
30e90 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
30ea0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
30eb0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
30ec0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
30ed0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
30ee0 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
30ef0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
30f00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30f10 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
30f20 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
30f30 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
30f40 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
30f50 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
30f60 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
30f70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30f80 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
30f90 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
30fa0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
30fb0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
30fc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
30fd0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
30fe0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
30ff0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31000 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
31010 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
31020 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
31030 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31040 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
31050 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
31060 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
31070 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31080 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
31090 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
310a0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
310b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
310c0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
310d0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
310e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
310f0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
31100 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
31110 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31120 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
31130 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
31140 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31150 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
31160 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
31170 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
31180 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
31190 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
311a0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
311b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
311c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
311d0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
311e0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
311f0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
31200 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
31210 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31220 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
31230 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
31240 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
31250 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
31260 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31270 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
31280 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
31290 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
312a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
312b0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
312c0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
312d0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
312e0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
312f0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
31300 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31310 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
31320 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31330 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
31340 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31350 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
31360 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
31370 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
31380 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
31390 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
313a0 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
313b0 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
313c0 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
313d0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
313e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
313f0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
31400 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
31410 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
31420 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
31430 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
31440 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
31450 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31460 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
31470 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31480 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
31490 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
314a0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
314b0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
314c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
314d0 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
314e0 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
314f0 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
31500 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
31510 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
31520 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
31530 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
31540 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
31550 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
31560 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
31570 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
31580 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
31590 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
315a0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
315b0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
315c0 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
315d0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
315e0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
315f0 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
31600 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
31610 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
31620 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
31630 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
31640 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
31650 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
31660 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
31670 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
31680 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
31690 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
316a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
316b0 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
316c0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
316d0 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
316e0 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
316f0 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
31700 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
31710 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
31720 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
31730 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
31740 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
31750 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
31760 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
31770 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
31780 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
31790 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
317a0 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
317b0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
317c0 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
317d0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
317e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
317f0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
31800 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
31810 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
31820 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
31830 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
31840 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
31850 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
31860 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
31870 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
31880 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
31890 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
318a0 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
318b0 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
318c0 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
318d0 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
318e0 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
318f0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
31900 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
31910 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
31920 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
31930 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
31940 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
31950 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
31960 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
31970 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e  s.** deleted.  ^
31980 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  When all collati
31990 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76  ng functions hav
319a0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
319b0 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a  e are deleted,.*
319c0 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e  * that collation
319d0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
319e0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
319f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
31a00 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ion callback is 
31a10 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63  invoked with a c
31a20 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20  opy of the pArg 
31a30 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
31a40 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64  data pointer and
31a50 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67   with two string
31a60 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  s in the encodin
31a70 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  g specified.** b
31a80 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61  y the eTextRep a
31a90 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f  rgument.  The co
31aa0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31ab0 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a   must return an.
31ac0 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  ** integer that 
31ad0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  is negative, zer
31ae0 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a  o, or positive.*
31af0 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  * if the first s
31b00 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
31b10 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
31b20 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
31b30 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73  e second,.** res
31b40 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f  pectively.  A co
31b50 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31b60 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74   must always ret
31b70 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
31b80 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
31b90 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
31ba0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
31bb0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31bc0 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
31bd0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
31be0 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
31bf0 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
31c00 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
31c10 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
31c20 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
31c30 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
31c40 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
31c50 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
31c60 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
31c70 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
31c80 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
31c90 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
31ca0 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
31cb0 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
31cc0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
31cd0 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
31ce0 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
31cf0 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
31d00 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
31d10 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
31d20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
31d30 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
31d40 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
31d50 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
31d60 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
31d70 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
31d80 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
31d90 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
31da0 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
31db0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
31dc0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
31dd0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
31de0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
31df0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
31e00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31e10 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
31e20 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
31e30 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
31e40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
31e50 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
31e60 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
31e70 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
31e80 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
31e90 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
31ea0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
31eb0 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
31ec0 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
31ed0 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
31ee0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
31ef0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
31f00 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
31f10 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
31f20 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
31f30 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
31f40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31f50 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
31f60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
31f70 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
31f80 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
31f90 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
31fa0 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
31fb0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
31fc0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
31fd0 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
31fe0 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
31ff0 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
32000 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32010 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
32020 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
32030 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
32040 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
32050 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
32060 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
32070 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32080 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
32090 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
320a0 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
320b0 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
320c0 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
320d0 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
320e0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
320f0 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
32100 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
32110 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
32120 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
32130 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
32140 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
32150 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
32160 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
32170 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
32180 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
32190 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
321a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
321b0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
321c0 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
321d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
321e0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
321f0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
32200 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
32210 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
32220 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
32230 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
32240 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
32250 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
32260 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
32270 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32280 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
32290 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
322a0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
322b0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
322c0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
322d0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
322e0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
322f0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
32300 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
32310 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
32320 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32330 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
32340 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
32350 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
32360 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
32370 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
32380 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
32390 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
323a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
323b0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
323c0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
323d0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
323e0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
323f0 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
32400 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
32410 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
32420 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
32430 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
32440 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
32450 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
32460 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
32470 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
32480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32490 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
324a0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
324b0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
324c0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
324d0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
324e0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
324f0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
32500 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
32510 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
32520 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
32530 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
32540 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
32550 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
32560 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
32570 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
32580 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
32590 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
325a0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
325b0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
325c0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
325d0 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
325e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
325f0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
32600 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
32610 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
32620 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
32630 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
32640 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
32650 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
32660 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
32670 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
32680 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
32690 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
326a0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
326b0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
326c0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
326d0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
326e0 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
326f0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
32700 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
32710 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
32720 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
32730 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
32740 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
32750 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
32760 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
32770 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
32780 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
32790 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
327a0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
327b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
327c0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
327d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
327e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
327f0 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
32800 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
32810 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
32820 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
32830 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
32840 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
32850 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
32860 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32870 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
32880 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32890 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
328a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
328b0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
328c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
328d0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
328e0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
328f0 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
32900 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
32910 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
32920 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
32930 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
32940 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
32950 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
32960 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
32970 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
32980 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
32990 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
329a0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
329b0 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
329c0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
329d0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
329e0 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
329f0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
32a00 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
32a10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
32a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
32a30 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
32a40 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
32a50 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
32a60 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
32a70 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
32a80 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
32a90 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
32aa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32ab0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
32ac0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
32ad0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
32ae0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
32af0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
32b00 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
32b10 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
32b20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
32b30 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
32b40 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
32b50 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
32b60 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
32b70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
32b80 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
32b90 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
32ba0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
32bb0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
32bc0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
32bd0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
32be0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
32bf0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
32c00 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
32c10 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
32c20 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
32c30 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32c40 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
32c50 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
32c60 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
32c70 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
32c80 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
32c90 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
32ca0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
32cb0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
32cc0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
32cd0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
32ce0 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
32cf0 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
32d00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
32d10 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
32d20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
32d30 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
32d40 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
32d50 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
32d60 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
32d70 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
32d80 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
32d90 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
32da0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
32db0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
32dc0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
32dd0 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
32de0 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
32df0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
32e00 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
32e10 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
32e20 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
32e30 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
32e40 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
32e50 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
32e60 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
32e70 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
32e80 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54  ort Time.**.** T
32e90 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
32ea0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
32eb0 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
32ec0 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
32ed0 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
32ee0 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
32ef0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
32f00 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
32f10 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
32f20 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
32f30 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
32f40 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
32f50 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
32f60 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
32f70 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
32f80 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
32f90 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
32fa0 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
32fb0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
32fc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
32fd0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
32fe0 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
32ff0 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
33000 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
33010 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
33020 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
33030 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
33040 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
33050 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
33060 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
33070 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
33080 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49  _vfs] object.  I
33090 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d  f the xSleep() m
330a0 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
330b0 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e  default VFS is n
330c0 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63  ot implemented c
330d0 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74  orrectly, or not
330e0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a   implemented at.
330f0 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65  ** all, then the
33100 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
33110 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79  ite3_sleep() may
33120 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68   deviate from th
33130 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a  e description.**
33140 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
33150 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a   paragraphs..*/.
33160 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
33170 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
33180 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
33190 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
331a0 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
331b0 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  les.**.** ^(If t
331c0 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
331d0 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
331e0 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
331f0 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
33200 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
33210 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
33220 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
33230 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
33240 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
33250 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
33260 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74   built-in [sqlit
33270 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a  e3_vfs | VFS].**
33280 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
33290 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
332a0 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76  y.)^  ^If this v
332b0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
332c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
332d0 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
332e0 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
332f0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
33300 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
33310 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
33320 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
33330 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
33340 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
33350 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   in more than on
33360 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61  e.** thread at a
33370 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f   time.  It is no
33380 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
33390 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
333a0 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b  riable.** if a [
333b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
333c0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73  ion] is being us
333d0 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ed at the same t
333e0 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74  ime in a separat
333f0 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20  e.** thread..** 
33400 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
33410 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
33420 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
33430 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
33440 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
33450 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
33460 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
33470 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
33480 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
33490 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61  and that this va
334a0 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e  riable remain un
334b0 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65  changed.** there
334c0 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  after..**.** ^Th
334d0 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
334e0 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
334f0 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20  may modify this 
33500 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75  variable and cau
33510 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e  se.** it to poin
33520 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
33530 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
33540 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75  e3_malloc].  ^Fu
33550 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68  rthermore,.** th
33560 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
33570 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
33580 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74  always assumes t
33590 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a  hat any string.*
335a0 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  * that this vari
335b0 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  able points to i
335c0 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  s held in memory
335d0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
335e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
335f0 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67  oc] and the prag
33600 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  ma may attempt t
33610 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f  o free that memo
33620 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ry.** using [sql
33630 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48  ite3_free]..** H
33640 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61  ence, if this va
33650 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69  riable is modifi
33660 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74  ed directly, eit
33670 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65  her it should be
33680 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72  .** made NULL or
33690 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
336a0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
336b0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
336c0 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c  malloc].** or el
336d0 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  se the use of th
336e0 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
336f0 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
33700 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65  should be avoide
33710 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  d..*/.SQLITE_EXT
33720 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
33730 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
33740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33750 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f  F: Test For Auto
33760 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20  -Commit Mode.** 
33770 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63  KEYWORDS: {autoc
33780 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  ommit mode}.**.*
33790 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
337a0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
337b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
337c0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
337d0 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
337e0 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
337f0 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
33800 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
33810 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
33820 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63  ctively.  ^Autoc
33830 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
33840 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
33850 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
33860 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
33870 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
33880 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ent..** ^Autocom
33890 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
338a0 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
338b0 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
338c0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
338d0 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
338e0 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
338f0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
33900 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
33910 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
33920 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
33930 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
33940 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
33950 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
33960 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
33970 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
33980 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
33990 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
339a0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
339b0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
339c0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
339d0 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
339e0 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
339f0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
33a00 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
33a10 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
33a20 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
33a30 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
33a40 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
33a50 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
33a60 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
33a70 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
33a80 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
33a90 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  ** connection wh
33aa0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
33ab0 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
33ac0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
33ad0 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ue.** is undefin
33ae0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
33af0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
33b00 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
33b10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
33b20 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20  nd The Database 
33b30 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70  Handle Of A Prep
33b40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
33b50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33b60 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65  3_db_handle inte
33b70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
33b80 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33b90 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
33ba0 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72  * to which a [pr
33bb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33bc0 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65  ] belongs.  ^The
33bd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33be0 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e  ction].** return
33bf0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62  ed by sqlite3_db
33c00 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73  _handle is the s
33c10 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
33c20 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
33c30 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20  t was the first 
33c40 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
33c50 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
33c60 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28  are_v2()] call (
33c70 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  or its variants)
33c80 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
33c90 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20  o.** create the 
33ca0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
33cb0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f   first place..*/
33cc0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
33cd0 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
33ce0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
33cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
33d00 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65  urn The Filename
33d10 20 46 6f 72 20 41 20 44 61 74 61 62 61 73 65 20   For A Database 
33d20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
33d30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
33d40 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69  _filename(D,N) i
33d50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33d60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
33d70 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f  filename.** asso
33d80 63 69 61 74 65 64 20 77 69 74 68 20 64 61 74 61  ciated with data
33d90 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63  base N of connec
33da0 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61  tion D.  ^The ma
33db0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
33dc0 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65  .** has the name
33dd0 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65   "main".  If the
33de0 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65  re is no attache
33df0 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20  d database N on 
33e00 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
33e10 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72  connection D, or
33e20 20 69 66 20 64 61 74 61 62 61 73 65 20 4e 20 69   if database N i
33e30 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20 6f 72  s a temporary or
33e40 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
33e50 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e  ase, then.** a N
33e60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
33e70 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
33e80 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 74  The filename ret
33e90 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
33ea0 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6f 75  nction is the ou
33eb0 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78  tput of the.** x
33ec0 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74  FullPathname met
33ed0 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46 53 5d  hod of the [VFS]
33ee0 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72  .  ^In other wor
33ef0 64 73 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ds, the filename
33f00 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 61  .** will be an a
33f10 62 73 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65  bsolute pathname
33f20 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20 66 69  , even if the fi
33f30 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74  lename used.** t
33f40 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
33f50 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77  ase originally w
33f60 61 73 20 61 20 55 52 49 20 6f 72 20 72 65 6c 61  as a URI or rela
33f70 74 69 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a  tive pathname..*
33f80 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
33f90 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d  lite3_db_filenam
33fa0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  e(sqlite3 *db, c
33fb0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
33fc0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
33fd0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
33fe0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
33ff0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
34000 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
34010 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
34020 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
34030 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
34040 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
34050 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
34060 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34070 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
34080 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
34090 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
340a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
340b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
340c0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
340d0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
340e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
340f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34100 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
34110 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
34120 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
34130 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
34140 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
34150 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
34160 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
34170 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34180 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
34190 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
341a0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
341b0 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
341c0 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
341d0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
341e0 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
341f0 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
34200 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
34210 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
34220 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
34230 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
34240 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
34250 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
34260 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
34270 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
34280 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
34290 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
342a0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
342b0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
342c0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
342d0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
342e0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
342f0 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
34300 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
34310 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
34320 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
34330 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
34340 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
34350 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
34360 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
34370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34380 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
34390 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
343a0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
343b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
343c0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
343d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
343e0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
343f0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
34400 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
34410 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
34420 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
34430 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
34440 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
34450 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
34460 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
34470 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
34480 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
34490 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
344a0 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
344b0 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
344c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
344d0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
344e0 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
344f0 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
34500 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
34510 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
34520 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
34530 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
34540 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34550 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
34560 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
34570 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
34580 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
34590 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
345a0 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
345b0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
345c0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
345d0 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
345e0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
345f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
34600 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
34610 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
34620 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
34630 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d  D..**.** The com
34640 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b  mit and rollback
34650 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20   hook callbacks 
34660 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e  are not reentran
34670 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  t..** The callba
34680 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
34690 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
346a0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
346b0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
346c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
346d0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
346e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
346f0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
34700 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
34710 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34720 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
34730 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
34740 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
34750 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
34760 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
34770 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
34780 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
34790 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
347a0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
347b0 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69   Note that runni
347c0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
347d0 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63   statements, inc
347e0 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74  luding SELECT st
347f0 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20  atements,.** or 
34800 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b  merely calling [
34810 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
34820 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
34830 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
34840 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
34850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34860 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
34870 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
34880 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
34890 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65  ..**.** ^Registe
348a0 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
348b0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
348c0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
348d0 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d  * ^When the comm
348e0 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
348f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
34900 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d   zero, the [COMM
34910 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  IT].** operation
34920 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63   is allowed to c
34930 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79  ontinue normally
34940 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69  .  ^If the commi
34950 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e  t hook.** return
34960 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
34970 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73   the [COMMIT] is
34980 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
34990 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
349a0 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68   ^The rollback h
349b0 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ook is invoked o
349c0 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61  n a rollback tha
349d0 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61  t results from a
349e0 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20   commit.** hook 
349f0 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65  returning non-ze
34a00 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77  ro, just as it w
34a10 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79  ould be with any
34a20 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e   other rollback.
34a30 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
34a40 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
34a50 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
34a60 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
34a70 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c  ave been.** roll
34a80 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
34a90 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
34aa0 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
34ab0 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
34ac0 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
34ad0 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
34ae0 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
34af0 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e  k to occur..** ^
34b00 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
34b10 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
34b20 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
34b30 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f  ction is.** auto
34b40 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
34b50 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68   back because th
34b60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
34b70 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
34b80 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
34b90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  the [sqlite3_upd
34ba0 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65  ate_hook()] inte
34bb0 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  rface..*/.void *
34bc0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
34bd0 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ook(sqlite3*, in
34be0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
34bf0 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
34c00 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
34c10 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
34c20 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
34c30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34c40 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
34c50 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
34c60 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
34c70 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
34c80 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  e_hook() interfa
34c90 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
34ca0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
34cb0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
34cc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34cd0 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  n] identified by
34ce0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
34cf0 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ent.** to be inv
34d00 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
34d10 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
34d20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
34d30 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ted..** ^Any cal
34d40 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
34d50 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
34d60 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
34d70 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
34d80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34d90 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
34da0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
34db0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
34dc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
34dd0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
34de0 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77  ke when a.** row
34df0 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
34e00 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
34e10 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
34e20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
34e30 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
34e40 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  py of the third 
34e50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
34e60 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
34e70 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65  ok()..** ^The se
34e80 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72  cond callback ar
34e90 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
34ea0 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
34eb0 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
34ec0 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
34ed0 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64  _UPDATE], depend
34ee0 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
34ef0 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
34f00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
34f10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
34f20 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
34f30 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  d fourth argumen
34f40 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ts to the callba
34f50 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74  ck contain point
34f60 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ers to the.** da
34f70 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65  tabase and table
34f80 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67   name containing
34f90 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f   the affected ro
34fa0 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c  w..** ^The final
34fb0 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
34fc0 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69  ter is the [rowi
34fd0 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a  d] of the row..*
34fe0 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f  * ^In the case o
34ff0 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
35000 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  s is the [rowid]
35010 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74   after the updat
35020 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
35030 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74  *.** ^(The updat
35040 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
35050 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
35060 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
35070 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
35080 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
35090 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
350a0 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a  _sequence).)^.**
350b0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72  .** ^In the curr
350c0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
350d0 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68  on, the update h
350e0 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e  ook.** is not in
350f0 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69  voked when dupli
35100 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20  cation rows are 
35110 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20  deleted because 
35120 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e  of an.** [ON CON
35130 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c  FLICT | ON CONFL
35140 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61  ICT REPLACE] cla
35150 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68  use.  ^Nor is th
35160 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
35170 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f   invoked when ro
35180 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75  ws are deleted u
35190 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61  sing the [trunca
351a0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
351b0 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69  ..** The excepti
351c0 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74  ons defined in t
351d0 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69  his paragraph mi
351e0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20  ght change in a 
351f0 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
35200 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
35210 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  ** The update ho
35220 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ok implementatio
35230 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
35240 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
35250 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
35260 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35270 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
35280 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
35290 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
352a0 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
352b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
352c0 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
352d0 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
352e0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
352f0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
35300 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
35310 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
35320 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a  e update hook..*
35330 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
35340 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
35350 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
35360 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
35370 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
35380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35390 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
353a0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
353b0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
353c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
353d0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
353e0 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a  D,C,P) function.
353f0 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ** returns the P
35400 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
35410 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
35420 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
35430 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35440 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
35450 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
35460 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a  t call on D..**.
35470 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
35480 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
35490 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c  hook()] and [sql
354a0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
354b0 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ok()].** interfa
354c0 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ces..*/.void *sq
354d0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
354e0 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
354f0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
35500 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
35510 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
35520 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
35530 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
35540 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
35550 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68  le Or Disable Sh
35560 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65  ared Pager Cache
35570 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73  .** KEYWORDS: {s
35580 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a  hared cache}.**.
35590 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
355a0 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
355b0 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e  ables the sharin
355c0 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  g of the databas
355d0 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73  e cache.** and s
355e0 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63  chema data struc
355f0 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64  tures between [d
35600 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35610 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  on | connections
35620 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65  ].** to the same
35630 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69   database. Shari
35640 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  ng is enabled if
35650 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
35660 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73   true.** and dis
35670 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
35680 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29  ument is false.)
35690 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73  ^.**.** ^Cache s
356a0 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
356b0 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66  d and disabled f
356c0 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f  or an entire pro
356d0 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73  cess..** This is
356e0 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20   a change as of 
356f0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
35700 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76  .5.0. In prior v
35710 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
35720 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61  e,.** sharing wa
35730 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
35740 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74  abled for each t
35750 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79  hread separately
35760 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61  ..**.** ^(The ca
35770 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  che sharing mode
35780 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74   set by this int
35790 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61  erface effects a
357a0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  ll subsequent.**
357b0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
357c0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
357d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
357e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
357f0 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73  en16()]..** Exis
35800 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f  ting database co
35810 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  nnections contin
35820 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69  ue use the shari
35830 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20  ng mode.** that 
35840 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74  was in effect at
35850 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77   the time they w
35860 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a  ere opened.)^.**
35870 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
35880 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
35890 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64  TE_OK] if shared
358a0 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c   cache was enabl
358b0 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
358c0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
358d0 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   An [error code]
358e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68   is returned oth
358f0 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erwise.)^.**.** 
35900 5e 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73  ^Shared cache is
35910 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
35920 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d  ault. But this m
35930 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a  ight change in.*
35940 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  * future release
35950 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70  s of SQLite.  Ap
35960 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
35970 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65  care about share
35980 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69  d.** cache setti
35990 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74  ng should set it
359a0 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a   explicitly..**.
359b0 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53  ** See Also:  [S
359c0 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63  QLite Shared-Cac
359d0 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20  he Mode].*/.int 
359e0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
359f0 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29  hared_cache(int)
35a00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35a10 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72  F: Attempt To Fr
35a20 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a  ee Heap Memory.*
35a30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35a40 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
35a50 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
35a60 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20  empts to free N 
35a70 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70  bytes.** of heap
35a80 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c   memory by deall
35a90 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65  ocating non-esse
35aa0 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ntial memory all
35ab0 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64  ocations.** held
35ac0 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
35ad0 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f   library.   Memo
35ae0 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65  ry used to cache
35af0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67   database.** pag
35b00 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65  es to improve pe
35b10 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20  rformance is an 
35b20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65  example of non-e
35b30 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e  ssential memory.
35b40 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c  .** ^sqlite3_rel
35b50 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65  ease_memory() re
35b60 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
35b70 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c   of bytes actual
35b80 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69  ly freed,.** whi
35b90 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65  ch might be more
35ba0 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68   or less than th
35bb0 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74  e amount request
35bc0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
35bd0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
35be0 72 79 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ry() routine is 
35bf0 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e  a no-op returnin
35c00 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c  g zero.** if SQL
35c10 69 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69  ite is not compi
35c20 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
35c30 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
35c40 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a  ANAGEMENT]..**.*
35c50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
35c60 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f  ite3_db_release_
35c70 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 69 6e 74  memory()].*/.int
35c80 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
35c90 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
35ca0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
35cb0 72 65 65 20 4d 65 6d 6f 72 79 20 55 73 65 64 20  ree Memory Used 
35cc0 42 79 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  By A Database Co
35cd0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
35ce0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 73  The sqlite3_db_s
35cf0 68 72 69 6e 6b 28 44 29 20 69 6e 74 65 72 66 61  hrink(D) interfa
35d00 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
35d10 72 65 65 20 61 73 20 6d 75 63 68 20 68 65 61 70  ree as much heap
35d20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70 6f  .** memory as po
35d30 73 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74 61  ssible from data
35d40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35d50 44 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a  D. Unlike the.**
35d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
35d70 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74 65  e_memory()] inte
35d80 72 66 61 63 65 2c 20 74 68 69 73 20 69 6e 74 65  rface, this inte
35d90 72 66 61 63 65 20 69 73 20 65 66 66 65 63 74 20  rface is effect 
35da0 65 76 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  even.** when the
35db0 6e 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  n [SQLITE_ENABLE
35dc0 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
35dd0 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  NT] compile-time
35de0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d   option is.** om
35df0 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  itted..**.** See
35e00 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
35e10 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
35e20 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
35e30 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  _db_release_memo
35e40 72 79 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  ry(sqlite3*);../
35e50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
35e60 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
35e70 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
35e80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
35e90 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
35ea0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35eb0 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
35ec0 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69  the.** soft limi
35ed0 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
35ee0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
35ef0 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
35f00 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
35f10 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76  ** ^SQLite striv
35f20 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20  es to keep heap 
35f30 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69  memory utilizati
35f40 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  on below the sof
35f50 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20  t heap.** limit 
35f60 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20  by reducing the 
35f70 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
35f80 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65  held in the page
35f90 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61   cache.** as hea
35fa0 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20  p memory usages 
35fb0 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c  approaches the l
35fc0 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f  imit..** ^The so
35fd0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
35fe0 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
35ff0 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69  even though SQLi
36000 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74  te strives to st
36010 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20  ay.** below the 
36020 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65  limit, it will e
36030 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20  xceed the limit 
36040 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65  rather than gene
36050 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49  rate.** an [SQLI
36060 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e  TE_NOMEM] error.
36070 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
36080 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
36090 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76  limit .** is adv
360a0 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
360b0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61  * ^The return va
360c0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
360d0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
360e0 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65  64() is the size
360f0 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20   of.** the soft 
36100 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72  heap limit prior
36110 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e   to the call.  ^
36120 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
36130 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
36140 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20   then no change 
36150 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73  is made to the s
36160 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
36170 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72   Hence, the curr
36180 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74  ent.** size of t
36190 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
361a0 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  it can be determ
361b0 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67  ined by invoking
361c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  .** sqlite3_soft
361d0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
361e0 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20  with a negative 
361f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
36200 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
36210 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20   N is zero then 
36220 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
36230 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e  mit is disabled.
36240 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66  .**.** ^(The sof
36250 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
36260 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20  not enforced in 
36270 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
36280 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66  ementation.** if
36290 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
362a0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74  following condit
362b0 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a  ions are true:.*
362c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
362d0 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  > The soft heap 
362e0 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20  limit is set to 
362f0 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65  zero..** <li> Me
36300 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
36310 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  is disabled usin
36320 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  g a combination 
36330 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b  of the.**      [
36340 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
36350 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
36360 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73  EMSTATUS],...) s
36370 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  tart-time option
36380 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65   and.**      the
36390 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
363a0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70  _MEMSTATUS] comp
363b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
363c0 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65  .** <li> An alte
363d0 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63  rnative page cac
363e0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
363f0 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75  n is specified u
36400 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71  sing.**      [sq
36410 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
36420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
36430 43 48 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c  CHE2],...)..** <
36440 6c 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63  li> The page cac
36450 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f  he allocates fro
36460 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79  m its own memory
36470 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a   pool supplied.*
36480 2a 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74  *      by [sqlit
36490 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
364a0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
364b0 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72  CHE],...) rather
364c0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72   than.**      fr
364d0 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20  om the heap..** 
364e0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65  </ul>)^.**.** Be
364f0 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
36500 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
36510 33 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  3, the soft heap
36520 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63   limit is enforc
36530 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ed.** regardless
36540 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
36550 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  ot the [SQLITE_E
36560 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
36570 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70  AGEMENT].** comp
36580 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
36590 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74  is invoked.  Wit
365a0 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
365b0 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
365c0 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74  NT],.** the soft
365d0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65   heap limit is e
365e0 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79  nforced on every
365f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
36600 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20  on.  Without.** 
36610 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
36620 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
36630 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ], the soft heap
36640 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65   limit is only e
36650 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20  nforced.** when 
36660 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
36670 74 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20  ted by the page 
36680 63 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20  cache.  Testing 
36690 73 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65  suggests that be
366a0 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67  cause.** the pag
366b0 65 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70  e cache is the p
366c0 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72  redominate memor
366d0 79 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65  y user in SQLite
366e0 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  , most.** applic
366f0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69  ations will achi
36700 65 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66  eve adequate sof
36710 74 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66  t heap limit enf
36720 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74  orcement without
36730 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b  .** the use of [
36740 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
36750 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
36760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63  ..**.** The circ
36770 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20  umstances under 
36780 77 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c  which SQLite wil
36790 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f  l enforce the so
367a0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61  ft heap limit ma
367b0 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  y.** changes in 
367c0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
367d0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71  of SQLite..*/.sq
367e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
367f0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
36800 6d 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e  mit64(sqlite3_in
36810 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t64 N);../*.** C
36820 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
36830 74 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69  ted Soft Heap Li
36840 6d 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  mit Interface.**
36850 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
36860 2a 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72  * This is a depr
36870 65 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f  ecated version o
36880 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
36890 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
368a0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
368b0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
368c0 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
368d0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
368e0 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79  tibility.** only
368f0 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69  .  All new appli
36900 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75  cations should u
36910 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
36920 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
36930 69 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63  it64()] interfac
36940 65 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68  e rather than th
36950 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54  is one..*/.SQLIT
36960 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
36970 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  d sqlite3_soft_h
36980 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29  eap_limit(int N)
36990 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
369a0 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61  EF: Extract Meta
369b0 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
369c0 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a  umn Of A Table.*
369d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
369e0 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
369f0 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
36a00 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
36a10 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
36a20 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
36a30 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
36a40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36a50 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
36a60 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
36a70 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
36a80 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
36a90 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
36aa0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
36ab0 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
36ac0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
36ad0 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75  rs to.** this fu
36ae0 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63  nction. ^The sec
36af0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
36b00 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
36b10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
36b20 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
36b30 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20  , "temp", or an 
36b40 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
36b50 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
36b60 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
36b70 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49  able or NULL. ^I
36b80 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
36b90 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
36ba0 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
36bb0 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
36bc0 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
36bd0 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
36be0 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74   used by the dat
36bf0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a  abase engine to.
36c00 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
36c10 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
36c20 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  erences..**.** ^
36c30 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
36c40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
36c50 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
36c60 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
36c70 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d  nd column.** nam
36c80 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
36c90 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
36ca0 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
36cb0 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
36cc0 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rs.** may be NUL
36cd0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61  L..**.** ^Metada
36ce0 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ta is returned b
36cf0 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  y writing to the
36d00 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e   memory location
36d10 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
36d20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65  5th.** and subse
36d30 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
36d40 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
36d50 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65  n. ^Any of these
36d60 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
36d70 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  e.** NULL, in wh
36d80 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72  ich case the cor
36d90 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65  responding eleme
36da0 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69  nt of metadata i
36db0 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a  s omitted..**.**
36dc0 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a   ^(<blockquote>.
36dd0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
36de0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
36df0 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e  > Parameter <th>
36e00 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20   Output<br>Type 
36e10 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f  <th>  Descriptio
36e20 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
36e30 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   5th <td> const 
36e40 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20  char* <td> Data 
36e50 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  type.** <tr><td>
36e60 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   6th <td> const 
36e70 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20  char* <td> Name 
36e80 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  of default colla
36e90 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a  tion sequence.**
36ea0 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74   <tr><td> 7th <t
36eb0 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
36ec0 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
36ed0 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
36ee0 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
36ef0 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64  <tr><td> 8th <td
36f00 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
36f10 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
36f20 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
36f30 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
36f40 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64  <tr><td> 9th <td
36f50 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
36f60 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
36f70 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d  n is [AUTOINCREM
36f80 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ENT].** </table>
36f90 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
36fa0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  >)^.**.** ^The m
36fb0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f  emory pointed to
36fc0 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65   by the characte
36fd0 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  r pointers retur
36fe0 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64  ned for the.** d
36ff0 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20  eclaration type 
37000 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  and collation se
37010 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20  quence is valid 
37020 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e  only until the n
37030 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  ext.** call to a
37040 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75  ny SQLite API fu
37050 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nction..**.** ^I
37060 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
37070 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  table is actuall
37080 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72  y a view, an [er
37090 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
370a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  urned..**.** ^If
370b0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
370c0 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
370d0 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
370e0 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
370f0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
37100 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
37110 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
37120 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
37130 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
37140 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
37150 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
37160 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
37170 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69  mn. ^(If there i
37180 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
37190 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
371a0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
371b0 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
371c0 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
371d0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
371e0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
371f0 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
37200 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
37210 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
37220 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
37230 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
37240 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
37250 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
37260 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
37270 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
37280 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  re>)^.**.** ^(Th
37290 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
372a0 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
372b0 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
372c0 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
372d0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
372e0 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
372f0 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
37300 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
37310 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
37320 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
37330 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
37340 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
37350 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
37360 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
37370 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37380 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
37390 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
373a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
373b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  )^.**.** ^This A
373c0 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
373d0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
373e0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
373f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
37400 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
37410 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
37420 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
37430 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
37440 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
37450 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
37460 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
37470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37480 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
37490 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
374a0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
374b0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
374c0 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
374d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
374e0 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
374f0 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
37500 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37510 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
37520 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
37530 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
37540 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
37550 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
37560 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
37570 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
37580 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
37590 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
375a0 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
375b0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
375c0 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
375d0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
375e0 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
375f0 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
37600 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
37610 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
37620 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
37630 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
37640 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
37650 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
37660 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
37670 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
37680 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
37690 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
376a0 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
376b0 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
376c0 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
376d0 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74  e loads an SQLit
376e0 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
376f0 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d  ary from the nam
37700 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed file..**.** ^
37710 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
37720 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
37730 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
37740 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51  to load an.** SQ
37750 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
37760 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
37770 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
37780 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  le..**.** ^The e
37790 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
377a0 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d  roc..** ^zProc m
377b0 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63  ay be 0, in whic
377c0 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
377d0 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
377e0 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74  nt.** defaults t
377f0 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
37800 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e  sion_init"..** ^
37810 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
37820 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
37830 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
37840 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  * [SQLITE_OK] on
37850 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
37860 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
37870 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
37880 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ong..** ^If an e
37890 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
378a0 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
378b0 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  0, then the.** [
378c0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
378d0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
378e0 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70  ace shall attemp
378f0 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a  t to.** fill *pz
37900 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
37910 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
37920 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
37930 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
37940 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
37950 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67  ()]. The calling
37960 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f   function.** sho
37970 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
37980 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20  mory by calling 
37990 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
379a0 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
379b0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
379c0 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
379d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  .** [sqlite3_ena
379e0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
379f0 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
37a00 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
37a10 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
37a20 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
37a30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
37a40 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61  ee also the [loa
37a50 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51  d_extension() SQ
37a60 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a  L function]..*/.
37a70 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
37a80 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
37a90 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
37aa0 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
37ab0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
37ac0 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
37ad0 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
37ae0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
37af0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
37b00 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
37b10 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
37b20 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
37b30 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
37b40 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
37b50 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
37b60 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
37b70 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
37b80 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
37b90 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
37ba0 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
37bb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
37bc0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
37bd0 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
37be0 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20  ng.**.** ^So as 
37bf0 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
37c00 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
37c10 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
37c20 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
37c30 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
37c40 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
37c50 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
37c60 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
37c70 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
37c80 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
37c90 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
37ca0 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
37cb0 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
37cc0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
37cd0 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
37ce0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
37cf0 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
37d00 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20   and off..**.** 
37d10 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69  ^Extension loadi
37d20 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  ng is off by def
37d30 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74  ault. See ticket
37d40 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c   #1863..** ^Call
37d50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
37d60 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
37d70 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74  on() routine wit
37d80 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f  h onoff==1.** to
37d90 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
37da0 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
37db0 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
37dc0 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
37dd0 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
37de0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
37df0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
37e00 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
37e10 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
37e20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37e30 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  : Automatically 
37e40 4c 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20  Load Statically 
37e50 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e  Linked Extension
37e60 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  s.**.** ^This in
37e70 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
37e80 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  he xEntryPoint()
37e90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37ea0 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65  invoked for.** e
37eb0 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73  ach new [databas
37ec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
37ed0 61 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20  at is created.  
37ee0 54 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73  The idea here is
37ef0 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50   that.** xEntryP
37f00 6f 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e  oint() is the en
37f10 74 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20  try point for a 
37f20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
37f30 64 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  d SQLite extensi
37f40 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f  on.** that is to
37f50 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
37f60 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c  y loaded into al
37f70 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  l new database c
37f80 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  onnections..**.*
37f90 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20  * ^(Even though 
37fa0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f  the function pro
37fb0 74 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61  totype shows tha
37fc0 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  t xEntryPoint() 
37fd0 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75  takes.** no argu
37fe0 6d 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e  ments and return
37ff0 73 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69  s void, SQLite i
38000 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69  nvokes xEntryPoi
38010 6e 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a  nt() with three.
38020 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64  ** arguments and
38030 20 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74   expects and int
38040 65 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69  eger result as i
38050 66 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20  f the signature 
38060 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20  of the.** entry 
38070 70 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66  point where as f
38080 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
38090 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
380a0 2a 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78  ** &nbsp;  int x
380b0 45 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26  EntryPoint(.** &
380c0 6e 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33  nbsp;    sqlite3
380d0 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20   *db,.** &nbsp; 
380e0 20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a     const char **
380f0 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62  pzErrMsg,.** &nb
38100 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72  sp;    const str
38110 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
38120 72 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b  routines *pThunk
38130 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a  .** &nbsp;  );.*
38140 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
38150 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66  uote>)^.**.** If
38160 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
38170 20 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74   routine encount
38180 65 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74  ers an error, it
38190 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a   should make *pz
381a0 45 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20  ErrMsg.** point 
381b0 74 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  to an appropriat
381c0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
381d0 28 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b  (obtained from [
381e0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
381f0 29 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72  )]).** and retur
38200 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  n an appropriate
38210 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20   [error code].  
38220 5e 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20  ^SQLite ensures 
38230 74 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a  that *pzErrMsg.*
38240 2a 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65  * is NULL before
38250 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e   calling the xEn
38260 74 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51  tryPoint().  ^SQ
38270 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
38280 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
38290 65 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73  e()] on *pzErrMs
382a0 67 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f  g after xEntryPo
382b0 69 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20  int() returns.  
382c0 5e 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72  ^If any.** xEntr
382d0 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73  yPoint() returns
382e0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b   an error, the [
382f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
38300 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
38310 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
38320 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63  te3_open_v2()] c
38330 61 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65  all that provoke
38340 64 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  d the xEntryPoin
38350 74 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a  t() will fail..*
38360 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
38370 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
38380 73 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20  sion(X) with an 
38390 65 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68  entry point X th
383a0 61 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a  at is already.**
383b0 20 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20   on the list of 
383c0 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
383d0 69 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65  ions is a harmle
383e0 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e  ss no-op. ^No en
383f0 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c  try point.** wil
38400 6c 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65  l be called more
38410 20 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65   than once for e
38420 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
38430 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  nection that is 
38440 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  opened..**.** Se
38450 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
38460 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
38470 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  nsion()]..*/.int
38480 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78   sqlite3_auto_ex
38490 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78  tension(void (*x
384a0 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64  EntryPoint)(void
384b0 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ));../*.** CAPI3
384c0 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d  REF: Reset Autom
384d0 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c  atic Extension L
384e0 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68  oading.**.** ^Th
384f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73  is interface dis
38500 61 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61  ables all automa
38510 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70  tic extensions p
38520 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67  reviously.** reg
38530 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
38540 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
38550 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  nsion()]..*/.voi
38560 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f  d sqlite3_reset_
38570 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
38580 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  oid);../*.** The
38590 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
385a0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
385b0 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
385c0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
385d0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
385e0 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
385f0 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
38600 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
38610 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
38620 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
38630 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
38640 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
38650 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
38660 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
38670 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
38680 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
38690 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
386a0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
386b0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
386c0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
386d0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
386e0 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
386f0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
38700 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
38710 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
38720 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
38730 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
38740 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
38750 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
38760 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
38770 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
38780 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
38790 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
387a0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
387b0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
387c0 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
387d0 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
387e0 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
387f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38800 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
38810 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
38820 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
38830 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62  ule {virtual tab
38840 6c 65 20