/ Hex Artifact Content
Login

Artifact d0e81fd4c72fbfdc786d3067e17a16a32f249428:


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: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5be0: 41 50 5f 5a 45 52 4f 5f 44 41 4d 41 47 45 20 70  AP_ZERO_DAMAGE p
5bf0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5c00: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
5c10: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
5c20: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
5c30: 73 73 2c 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ss, the value of
5c40: 0a 2a 2a 20 65 61 63 68 20 62 79 74 65 20 69 6e  .** each byte in
5c50: 20 61 20 66 69 6c 65 20 69 73 20 61 20 76 61 6c   a file is a val
5c60: 75 65 20 74 68 61 74 20 77 61 73 20 61 63 74 75  ue that was actu
5c70: 61 6c 6c 79 20 77 72 69 74 74 65 6e 0a 2a 2a 20  ally written.** 
5c80: 69 6e 74 6f 20 74 68 61 74 20 62 79 74 65 20 61  into that byte a
5c90: 74 20 73 6f 6d 65 20 70 6f 69 6e 74 2e 20 20 49  t some point.  I
5ca0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 61  n other words, a
5cb0: 20 63 72 61 73 68 20 77 69 6c 6c 0a 2a 2a 20 6e   crash will.** n
5cc0: 6f 74 20 69 6e 74 72 6f 64 75 63 65 20 67 61 72  ot introduce gar
5cd0: 62 61 67 65 20 6f 72 20 72 61 6e 64 6f 6d 6e 65  bage or randomne
5ce0: 73 73 20 69 6e 74 6f 20 61 20 66 69 6c 65 2c 20  ss into a file, 
5cf0: 61 6e 64 20 62 79 74 65 20 6f 66 0a 2a 2a 20 61  and byte of.** a
5d00: 20 66 69 6c 65 20 74 68 61 74 20 61 72 65 20 6e   file that are n
5d10: 65 76 65 72 20 77 72 69 74 74 65 6e 20 77 69 6c  ever written wil
5d20: 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 76 61 6c  l not change val
5d30: 75 65 73 20 64 75 65 20 74 6f 0a 2a 2a 20 77 72  ues due to.** wr
5d40: 69 74 65 73 20 74 6f 20 6e 65 61 72 62 79 20 62  ites to nearby b
5d50: 79 74 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ytes..*/.#define
5d60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5d70: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
5d80: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
5d90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5da0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
5db0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5dc0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5dd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5de0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
5df0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
5e00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5e10: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
5e20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5e30: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
5e40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5e50: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
5e60: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
5e70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5e80: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
5e90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ea0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
5eb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
5ec0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
5ed0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
5ee0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5ef0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
5f00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
5f30: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5f40: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
5f50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5f60: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
5f70: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
5f80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5f90: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
5fa0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5fb0: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
5fc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
5fd0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
5fe0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
5ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6000: 50 5f 5a 45 52 4f 5f 44 41 4d 41 47 45 20 20 20  P_ZERO_DAMAGE   
6010: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 31           0x00001
6020: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
6030: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
6040: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
6050: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
6060: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
6070: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6080: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
6090: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
60a0: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
60b0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
60c0: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
60d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
60e0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
60f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6100: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
6110: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
6120: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
6130: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
6140: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
6150: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6170: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
6180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6190: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
61a0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
61b0: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
61c0: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
61d0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
61e0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
61f0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
6200: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6210: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6220: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6230: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6240: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6250: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6260: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6270: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6280: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6290: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
62a0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
62b0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
62c0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
62d0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
62e0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
62f0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
6300: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6310: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
6320: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
6330: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
6340: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
6350: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
6360: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
6370: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6380: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6390: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
63a0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
63b0: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
63c0: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
63d0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
63e0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
63f0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
6400: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
6410: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6420: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6430: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
6440: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
6450: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
6460: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
6470: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6480: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6490: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
64a0: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
64b0: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
64c0: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
64d0: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
64e0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
64f0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
6500: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
6510: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
6520: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6530: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6540: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
6550: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
6560: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
6570: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
6580: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
6590: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
65a0: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
65b0: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
65c0: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
65d0: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
65e0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
65f0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
6600: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
6610: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
6620: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
6630: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6640: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
6650: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
6660: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
6670: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
6680: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
6690: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
66a0: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
66b0: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
66c0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
66d0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
66e0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
66f0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
6700: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
6710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6720: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
6730: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
6740: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6750: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
6760: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
6770: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
6780: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
6790: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
67a0: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
67b0: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
67c0: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
67d0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
67e0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
67f0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
6800: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
6810: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
6820: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
6830: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
6840: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
6850: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
6860: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
6870: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
6880: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6890: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
68a0: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
68b0: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
68c0: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
68d0: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
68e0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
68f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
6900: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
6910: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
6920: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
6930: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6940: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
6950: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
6960: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
6970: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6980: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6990: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
69a0: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
69b0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
69c0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
69d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
69e0: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
69f0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
6a00: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6a10: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
6a20: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
6a30: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
6a40: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
6a50: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
6a60: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
6a70: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
6a80: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
6a90: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
6aa0: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
6ab0: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
6ac0: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
6ad0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
6ae0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
6af0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6b00: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
6b10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6b20: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
6b30: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
6b40: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
6b50: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
6b60: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
6b70: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
6b80: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
6b90: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
6ba0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
6bb0: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
6bc0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
6bd0: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
6be0: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
6bf0: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
6c00: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
6c10: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
6c20: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
6c30: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
6c40: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
6c50: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
6c60: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
6c70: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
6c80: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
6c90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
6ca0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
6cb0: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
6cc0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
6cd0: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
6ce0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
6cf0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
6d00: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
6d10: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
6d20: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
6d30: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
6d40: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
6d50: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
6d60: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
6d70: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
6d80: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
6d90: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
6da0: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
6db0: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
6dc0: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
6dd0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
6de0: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
6df0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6e00: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
6e10: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6e20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
6e30: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
6e40: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6e50: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
6e60: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
6e70: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
6e80: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
6e90: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
6ea0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6eb0: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
6ec0: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
6ed0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
6ee0: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
6ef0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
6f00: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
6f10: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
6f20: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
6f30: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
6f40: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
6f50: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
6f60: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6f70: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
6f80: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
6f90: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6fa0: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6fb0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6fc0: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6fd0: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6fe0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6ff0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
7000: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
7010: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
7020: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
7030: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
7040: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
7050: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
7060: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
7070: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
7080: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
7090: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
70a0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
70b0: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
70c0: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
70d0: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
70e0: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
70f0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
7100: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
7110: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
7120: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
7130: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
7140: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
7150: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
7160: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
7170: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
7180: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
7190: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
71a0: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
71b0: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
71c0: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
71d0: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
71e0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
71f0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
7200: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
7210: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
7220: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
7230: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
7240: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
7250: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
7260: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
7270: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
7280: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
7290: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
72a0: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
72b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
72c0: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
72d0: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
72e0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
72f0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
7300: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
7310: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
7320: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
7330: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
7340: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
7350: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
7360: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
7370: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
7380: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
7390: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
73a0: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
73b0: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
73c0: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
73d0: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
73e0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
73f0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
7400: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
7410: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
7420: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
7430: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
7440: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
7450: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
7460: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
7470: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
7480: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
7490: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
74a0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
74b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
74c0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
74d0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
74e0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
74f0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
7500: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
7510: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
7520: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7530: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
7540: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7550: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
7560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7570: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
7580: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7590: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
75a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
75b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
75c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
75d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
75e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
75f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
7600: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7610: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
7620: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7630: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
7640: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7650: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
7660: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
7670: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7680: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
7690: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
76a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
76b0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
76c0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
76d0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
76e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
76f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7700: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
7710: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
7720: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
7730: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
7740: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
7750: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
7760: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
7770: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
7780: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
7790: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
77a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
77b0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
77c0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
77d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
77e0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
77f0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7800: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
7810: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7820: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
7830: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
7840: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
7850: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7860: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
7870: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7880: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
7890: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
78a0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
78b0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
78c0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
78d0: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
78e0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
78f0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
7900: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
7910: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
7920: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
7930: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
7940: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
7950: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
7960: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
7970: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
7980: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
7990: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
79a0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
79b0: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
79c0: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
79d0: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
79e0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
79f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7a00: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
7a10: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
7a20: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7a30: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
7a40: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
7a50: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
7a60: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7a70: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
7a80: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
7a90: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7aa0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7ab0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
7ac0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
7ad0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
7ae0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
7af0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7b00: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
7b10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
7b20: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
7b30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
7b40: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7b50: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
7b60: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
7b70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7b80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
7b90: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
7ba0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
7bb0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
7bc0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
7bd0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
7be0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
7bf0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
7c00: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
7c10: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
7c20: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
7c30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7c40: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
7c50: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
7c60: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
7c70: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7c80: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
7c90: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
7ca0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
7cb0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
7cc0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
7cd0: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
7ce0: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
7cf0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
7d00: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
7d10: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
7d20: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
7d30: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
7d40: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
7d50: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
7d60: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
7d70: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
7d80: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7d90: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
7da0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
7db0: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
7dc0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
7dd0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
7de0: 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 2 */.  /* Add
7df0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
7e00: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
7e10: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
7e20: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7e30: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
7e40: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
7e50: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
7e60: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
7e70: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
7e80: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
7e90: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
7ea0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
7eb0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7ec0: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
7ed0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7ee0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
7ef0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
7f00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
7f10: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
7f20: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
7f30: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
7f40: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
7f50: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7f60: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
7f70: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
7f80: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
7f90: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
7fa0: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
7fb0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7fc0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
7fd0: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
7fe0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7ff0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
8000: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
8010: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
8020: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
8030: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
8040: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
8050: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
8060: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
8070: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
8080: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
8090: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
80a0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
80b0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
80c0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
80d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
80e0: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
80f0: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
8100: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
8110: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
8120: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
8130: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
8140: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
8150: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
8160: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
8170: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
8180: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
8190: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
81a0: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
81b0: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
81c0: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
81d0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
81e0: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
81f0: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
8200: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
8210: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
8220: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
8230: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ster..**.** The 
8240: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8250: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8260: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8270: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8280: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8290: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
82a0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
82b0: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
82c0: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
82d0: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
82e0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
82f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8300: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
8310: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
8320: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
8330: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
8340: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
8350: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
8360: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
8370: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
8380: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8390: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
83a0: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
83b0: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
83c0: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
83d0: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
83e0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
83f0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
8400: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
8410: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
8420: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8430: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
8440: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
8450: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
8460: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8470: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
8480: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
8490: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
84a0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
84b0: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
84c0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
84d0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
84e0: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
84f0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
8500: 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45  ** ^(The [SQLITE
8510: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
8520: 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TED] opcode is g
8530: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
8540: 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65  lly by.** SQLite
8550: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c   and sent to all
8560: 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20   VFSes in place 
8570: 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65  of a call to the
8580: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a   xSync method.**
8590: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
85a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  se connection ha
85b0: 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  s [PRAGMA synchr
85c0: 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46  onous] set to OF
85d0: 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65  F.)^.** Some spe
85e0: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e  cialized VFSes n
85f0: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
8600: 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72  in order to oper
8610: 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a  ate correctly.**
8620: 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79   when [PRAGMA sy
8630: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
8640: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
8650: 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20  FF] is set, but 
8660: 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64  most .** VFSes d
8670: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
8680: 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c  signal and shoul
8690: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
86a0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  e this opcode..*
86b0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
86c0: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
86d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
86e0: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
86f0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64  s.** opcode as d
8700: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
8710: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
8720: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
8730: 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68  ized VFSes.** th
8740: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
8750: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  .  .**.** ^The [
8760: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
8770: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
8780: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
8790: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
87a0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
87b0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
87c0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
87d0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
87e0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
87f0: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
8800: 65 72 20 74 6f 20 77 6f 72 6b 20 74 6f 20 70 72  er to work to pr
8810: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
8820: 20 61 67 61 69 6e 73 74 0a 2a 2a 20 61 6e 74 69   against.** anti
8830: 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e  -virus programs.
8840: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
8850: 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69  e windows VFS wi
8860: 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65  ll retry file re
8870: 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74  ad,.** file writ
8880: 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65  e, and file dele
8890: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70  te operations up
88a0: 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69   to 10 times, wi
88b0: 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66  th a delay.** of
88c0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
88d0: 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73   before the firs
88e0: 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68  t retry and with
88f0: 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65   the delay incre
8900: 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61  asing.** by an a
8910: 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c  dditional 25 mil
8920: 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65  liseconds with e
8930: 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72  ach subsequent r
8940: 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  etry.  This.** o
8950: 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 6f  pcode allows tho
8960: 73 65 20 74 6f 20 76 61 6c 75 65 73 20 28 31 30  se to values (10
8970: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
8980: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
8990: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
89a0: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
89b0: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
89c0: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
89d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
89e0: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
89f0: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
8a00: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
8a10: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
8a20: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
8a30: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
8a40: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
8a50: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
8a60: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
8a70: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
8a80: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
8a90: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
8aa0: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
8ab0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
8ac0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
8ad0: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
8ae0: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
8af0: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
8b00: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
8b10: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
8b20: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
8b30: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
8b40: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
8b50: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
8b60: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
8b70: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
8b80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
8b90: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
8ba0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8bb0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
8bc0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
8bd0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
8be0: 41 48 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  AHead Log] setti
8bf0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
8c00: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
8c10: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
8c20: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
8c30: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
8c40: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
8c50: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
8c60: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
8c70: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
8c80: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
8c90: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8ca0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
8cb0: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
8cc0: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
8cd0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
8ce0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
8cf0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
8d00: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
8d10: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
8d20: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
8d30: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
8d40: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
8d50: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
8d60: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
8d70: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
8d80: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
8d90: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
8da0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
8db0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
8dc0: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
8dd0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
8de0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
8df0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
8e00: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
8e10: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
8e20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8e30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
8e40: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
8e50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
8e60: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
8e70: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
8e80: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
8e90: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
8ea0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
8eb0: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
8ec0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
8ed0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
8ee0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
8ef0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
8f00: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
8f10: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  setting..**.** ^
8f20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8f30: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
8f40: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
8f50: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
8f60: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
8f70: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
8f80: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
8f90: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
8fa0: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
8fb0: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
8fc0: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
8fd0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
8fe0: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
8ff0: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
9000: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
9010: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
9020: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
9030: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9040: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
9050: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
9060: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
9070: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
9080: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
9090: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
90a0: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
90b0: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
90c0: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
90d0: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
90e0: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
90f0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
9100: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
9110: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
9120: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
9130: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
9140: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
9150: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
9160: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
9170: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9180: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
9190: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
91a0: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
91b0: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
91c0: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
91d0: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
91e0: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
91f0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
9200: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
9210: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
9220: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
9230: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
9240: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
9250: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
9260: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
9270: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
9280: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
9290: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
92a0: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
92b0: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
92c0: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
92d0: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2f 0a 23 64   use only..*/.#d
92e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
92f0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
9300: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
9310: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
9320: 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64  XYFILE      2.#d
9330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
9340: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
9350: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
9360: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
9370: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
9380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9390: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
93a0: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
93b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
93c0: 5f 53 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64  _SIZE       6.#d
93d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
93e0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
93f0: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
9400: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9410: 4f 4d 49 54 54 45 44 20 20 20 20 20 38 0a 23 64  OMITTED     8.#d
9420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9430: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
9440: 59 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51  Y   9.#define SQ
9450: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9460: 53 54 5f 57 41 4c 20 20 20 20 20 31 30 0a 23 64  ST_WAL     10.#d
9470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9480: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
9490: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
94a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
94b0: 4d 45 20 20 20 20 20 20 20 20 20 31 32 0a 0a 2f  ME         12../
94c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
94d0: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
94e0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
94f0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
9500: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
9510: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
9520: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
9530: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
9540: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
9550: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
9560: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
9570: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
9580: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
9590: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
95a0: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
95b0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
95c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
95d0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
95e0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
95f0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
9600: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
9610: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
9620: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
9630: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
9640: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
9650: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
9660: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
9670: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
9680: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
9690: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
96a0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
96b0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
96c0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
96d0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
96e0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
96f0: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
9700: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
9710: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
9720: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
9730: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
9740: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
9750: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
9760: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
9770: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
9780: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
9790: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
97a0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
97b0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
97c0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
97d0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
97e0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
97f0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
9800: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
9810: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
9820: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
9830: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
9840: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
9850: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
9860: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
9870: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
9880: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
9890: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
98a0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
98b0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
98c0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
98d0: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
98e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
98f0: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
9900: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
9910: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
9920: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
9930: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
9940: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
9950: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
9960: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
9970: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
9980: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
9990: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
99a0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
99b0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
99c0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
99d0: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
99e0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
99f0: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
9a00: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
9a10: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
9a20: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
9a30: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
9a40: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
9a50: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
9a60: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
9a70: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
9a80: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
9a90: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
9aa0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
9ab0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
9ac0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9ad0: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
9ae0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
9af0: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
9b00: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
9b10: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
9b20: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
9b30: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
9b40: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
9b50: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
9b60: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
9b70: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
9b80: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
9b90: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
9ba0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
9bb0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
9bc0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
9bd0: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
9be0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
9bf0: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
9c00: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
9c10: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
9c20: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
9c30: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
9c40: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
9c50: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
9c60: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
9c70: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
9c80: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
9c90: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
9ca0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
9cb0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
9cc0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
9cd0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
9ce0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
9cf0: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
9d00: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
9d10: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
9d20: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
9d30: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
9d40: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
9d50: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
9d60: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
9d70: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
9d80: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
9d90: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
9da0: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
9db0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
9dc0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20  more than.** 10 
9dd0: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
9de0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
9df0: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
9e00: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
9e10: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
9e20: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
9e30: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
9e40: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
9e50: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
9e60: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
9e70: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
9e80: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
9e90: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
9ea0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
9eb0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
9ec0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
9ed0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
9ee0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
9ef0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
9f00: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
9f10: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
9f20: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
9f30: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
9f40: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
9f50: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
9f60: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
9f70: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
9f80: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
9f90: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
9fa0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
9fb0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
9fc0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
9fd0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
9fe0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
9ff0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
a000: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
a010: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
a020: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
a030: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
a040: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
a050: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
a060: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
a070: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
a080: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
a090: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
a0a0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
a0b0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
a0c0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
a0d0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
a0e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
a0f0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
a100: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
a110: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
a120: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
a130: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
a140: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
a150: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
a160: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
a170: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
a180: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
a190: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
a1a0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
a1b0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
a1c0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
a1d0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
a1e0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
a1f0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
a200: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
a210: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
a220: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
a230: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
a240: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
a250: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
a260: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
a270: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
a280: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
a290: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
a2a0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
a2b0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
a2c0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
a2d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
a2e0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
a2f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
a300: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
a310: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
a320: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
a330: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
a340: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
a350: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
a360: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
a370: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
a380: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
a390: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
a3a0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
a3b0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
a3c0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
a3d0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
a3e0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
a3f0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
a400: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
a410: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
a420: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
a430: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
a440: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
a450: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
a460: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
a470: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
a480: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
a490: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
a4a0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
a4b0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
a4c0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
a4d0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
a4e0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
a4f0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
a500: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
a510: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
a520: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
a530: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
a540: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
a550: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
a560: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
a570: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
a580: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
a590: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
a5a0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
a5b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
a5c0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
a5d0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
a5e0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
a5f0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
a600: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
a610: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
a620: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
a630: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
a640: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
a650: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
a660: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
a670: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
a680: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
a690: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
a6a0: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
a6b0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
a6c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
a6d0: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
a6e0: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
a6f0: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
a700: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
a710: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
a720: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
a730: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
a740: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
a750: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
a760: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
a770: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
a780: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
a790: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
a7a0: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
a7b0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
a7c0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
a7d0: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
a7e0: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
a7f0: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
a800: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
a810: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
a820: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
a830: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
a840: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
a850: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
a860: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
a870: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
a880: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
a890: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
a8a0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
a8b0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
a8c0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
a8d0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
a8e0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
a8f0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
a900: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
a910: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
a920: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
a930: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
a940: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
a950: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
a960: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
a970: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
a980: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
a990: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
a9a0: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
a9b0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
a9c0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
a9d0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
a9e0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
a9f0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
aa00: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
aa10: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
aa20: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
aa30: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
aa40: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
aa50: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
aa60: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
aa70: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
aa80: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
aa90: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
aaa0: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
aab0: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
aac0: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
aad0: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
aae0: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
aaf0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
ab00: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
ab10: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
ab20: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
ab30: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
ab40: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
ab50: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ab60: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
ab70: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
ab80: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
ab90: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
aba0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
abb0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
abc0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
abd0: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
abe0: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
abf0: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
ac00: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
ac10: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
ac20: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
ac30: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
ac40: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
ac50: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
ac60: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
ac70: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
ac80: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
ac90: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
aca0: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
acb0: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
acc0: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
acd0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
ace0: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
acf0: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
ad00: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
ad10: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
ad20: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
ad30: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
ad40: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
ad50: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
ad60: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
ad70: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
ad80: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
ad90: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
ada0: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
adb0: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
adc0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
add0: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
ade0: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
adf0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ae00: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
ae10: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
ae20: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
ae30: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
ae40: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
ae50: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
ae60: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
ae70: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
ae80: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
ae90: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
aea0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
aeb0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
aec0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
aed0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
aee0: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
aef0: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
af00: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
af10: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
af20: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
af30: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
af40: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
af50: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
af60: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
af70: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
af80: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
af90: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
afa0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
afb0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
afc0: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
afd0: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
afe0: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
aff0: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
b000: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
b010: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
b020: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
b030: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
b040: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
b050: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
b060: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
b070: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
b080: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
b090: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
b0a0: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
b0b0: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
b0c0: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
b0d0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
b0e0: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
b0f0: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
b100: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
b110: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
b120: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
b130: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
b140: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
b150: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
b160: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
b170: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
b180: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
b190: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
b1a0: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
b1b0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
b1c0: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
b1d0: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
b1e0: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
b1f0: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
b200: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
b210: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
b220: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
b230: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
b240: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
b250: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
b260: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
b270: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
b280: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
b290: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
b2a0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
b2b0: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
b2c0: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
b2d0: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
b2e0: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
b2f0: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
b300: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
b310: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
b320: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
b330: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
b340: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
b350: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
b360: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
b370: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
b380: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
b390: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
b3a0: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
b3b0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
b3c0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
b3d0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
b3e0: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
b3f0: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
b400: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
b410: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
b420: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
b430: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
b440: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
b450: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
b460: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
b470: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
b480: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
b490: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
b4a0: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
b4b0: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
b4c0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
b4d0: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
b4e0: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
b4f0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
b500: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
b510: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
b520: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
b530: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
b540: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
b550: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
b560: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
b570: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
b580: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
b590: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
b5a0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
b5b0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
b5c0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
b5d0: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
b5e0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
b5f0: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
b600: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
b610: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
b620: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
b630: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
b640: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
b650: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b660: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
b670: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
b680: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
b690: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
b6a0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
b6b0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
b6c0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
b6d0: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
b6e0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
b6f0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
b700: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
b710: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
b720: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
b730: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
b740: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
b750: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b760: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b770: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
b780: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
b790: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b7a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b7b0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
b7c0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
b7d0: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
b7e0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
b7f0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
b800: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
b810: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
b820: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
b830: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
b840: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
b850: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
b860: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
b870: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
b880: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
b890: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
b8a0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
b8b0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
b8c0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
b8d0: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
b8e0: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
b8f0: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
b900: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
b910: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
b920: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
b930: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
b940: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
b950: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
b960: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
b970: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
b980: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
b990: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
b9a0: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
b9b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
b9c0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
b9d0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
b9e0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
b9f0: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
ba00: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
ba10: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
ba20: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
ba30: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
ba40: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
ba50: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
ba60: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
ba70: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
ba80: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
ba90: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
baa0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
bab0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
bac0: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
bad0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
bae0: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
baf0: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
bb00: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
bb10: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
bb20: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
bb30: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
bb40: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
bb50: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
bb60: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
bb70: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
bb80: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
bb90: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
bba0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
bbb0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
bbc0: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
bbd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
bbe0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
bbf0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
bc00: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
bc10: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
bc20: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
bc30: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
bc40: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
bc50: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
bc60: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
bc70: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
bc80: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
bc90: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
bca0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
bcb0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
bcc0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
bcd0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
bce0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
bcf0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
bd00: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
bd10: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
bd20: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
bd30: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
bd40: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
bd50: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
bd60: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
bd70: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
bd80: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
bd90: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
bda0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
bdb0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
bdc0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
bdd0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
bde0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
bdf0: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
be00: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
be10: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
be20: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
be30: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
be40: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
be50: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
be60: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
be70: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
be80: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
be90: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
bea0: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
beb0: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
bec0: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
bed0: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
bee0: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
bef0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
bf00: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
bf10: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
bf20: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
bf30: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
bf40: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
bf50: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
bf60: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
bf70: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
bf80: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
bf90: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
bfa0: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
bfb0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
bfc0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
bfd0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
bfe0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
bff0: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
c000: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
c010: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
c020: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
c030: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
c040: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
c050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
c060: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
c070: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
c080: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
c090: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
c0a0: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
c0b0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
c0c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
c0d0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
c0e0: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
c0f0: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
c100: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
c110: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
c120: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
c130: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
c140: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
c150: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
c160: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
c170: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
c180: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
c190: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
c1a0: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
c1b0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
c1c0: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
c1d0: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
c1e0: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
c1f0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
c200: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c210: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
c220: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
c230: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
c240: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
c250: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
c260: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
c270: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
c280: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
c290: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
c2a0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
c2b0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
c2c0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
c2d0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
c2e0: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
c2f0: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
c300: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
c310: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
c320: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
c330: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
c340: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
c350: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
c360: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
c370: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
c380: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
c390: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
c3a0: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
c3b0: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
c3c0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
c3d0: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
c3e0: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
c3f0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
c400: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
c410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
c420: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
c430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
c440: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
c450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c460: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
c470: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
c480: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
c490: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
c4a0: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
c4b0: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
c4c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
c4d0: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
c4e0: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
c4f0: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
c500: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
c510: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
c520: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
c530: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
c540: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
c550: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
c560: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
c570: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
c580: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
c590: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
c5a0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
c5b0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
c5c0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
c5d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
c5e0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
c5f0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
c600: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
c610: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
c620: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
c630: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
c640: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
c650: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
c660: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
c670: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
c680: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
c690: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
c6a0: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
c6b0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
c6c0: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
c6d0: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
c6e0: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
c6f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
c700: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
c710: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
c720: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
c730: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
c740: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
c750: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
c760: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
c770: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
c780: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
c790: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
c7a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c7b0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
c7c0: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
c7d0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
c7e0: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
c7f0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
c800: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c810: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
c820: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
c830: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
c840: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
c850: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
c860: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
c870: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
c880: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
c890: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
c8a0: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
c8b0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
c8c0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
c8d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
c8e0: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
c8f0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
c900: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
c910: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
c920: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
c930: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
c940: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c950: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
c960: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
c970: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
c980: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
c990: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
c9a0: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
c9b0: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
c9c0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c9d0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
c9e0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
c9f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ca00: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
ca10: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
ca20: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
ca30: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
ca40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
ca50: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
ca60: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
ca70: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
ca80: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
ca90: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
caa0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
cab0: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
cac0: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
cad0: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
cae0: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
caf0: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
cb00: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
cb10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
cb20: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
cb30: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
cb40: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
cb50: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
cb60: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
cb70: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
cb80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
cb90: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
cba0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
cbb0: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
cbc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
cbd0: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
cbe0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
cbf0: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
cc00: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
cc10: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
cc20: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
cc30: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
cc40: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
cc50: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
cc60: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
cc70: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
cc80: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
cc90: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
cca0: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
ccb0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
ccc0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
ccd0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
cce0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
ccf0: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
cd00: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
cd10: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
cd20: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
cd30: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
cd40: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
cd50: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
cd60: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
cd70: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
cd80: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
cd90: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
cda0: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
cdb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
cdc0: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
cdd0: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
cde0: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
cdf0: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
ce00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ce10: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
ce20: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
ce30: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
ce40: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
ce50: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
ce60: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
ce70: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ce80: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
ce90: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
cea0: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
ceb0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
cec0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
ced0: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
cee0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
cef0: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
cf00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
cf10: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
cf20: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
cf30: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
cf40: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
cf50: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
cf60: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
cf70: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
cf80: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
cf90: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
cfa0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
cfb0: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
cfc0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
cfd0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
cfe0: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
cff0: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
d000: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
d010: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
d020: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
d030: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
d040: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
d050: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
d060: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
d070: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
d080: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
d090: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
d0a0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
d0b0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
d0c0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
d0d0: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
d0e0: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
d0f0: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
d100: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
d110: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
d120: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
d130: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
d140: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
d150: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
d160: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
d170: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
d180: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
d190: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
d1a0: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
d1b0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
d1c0: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
d1d0: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
d1e0: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
d1f0: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
d200: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
d210: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
d220: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
d230: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
d240: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
d250: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
d260: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
d270: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
d280: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
d290: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
d2a0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
d2b0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
d2c0: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
d2d0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
d2e0: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
d2f0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
d300: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
d310: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d320: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
d330: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
d340: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
d350: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
d360: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
d370: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
d380: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
d390: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
d3a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
d3b0: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
d3c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
d3d0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
d3e0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
d3f0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
d400: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
d410: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
d420: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
d430: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
d440: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
d450: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
d460: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
d470: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
d480: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
d490: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
d4a0: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
d4b0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
d4c0: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
d4d0: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
d4e0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
d4f0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
d500: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
d510: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
d520: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
d530: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
d540: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
d550: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
d560: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
d570: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
d580: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
d590: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
d5a0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
d5b0: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
d5c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
d5d0: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
d5e0: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
d5f0: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
d600: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
d610: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
d620: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
d630: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d640: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
d650: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
d660: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
d670: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
d680: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
d690: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
d6a0: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
d6b0: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
d6c0: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
d6d0: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
d6e0: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
d6f0: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
d700: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
d710: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
d720: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
d730: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
d740: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
d750: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
d760: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
d770: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
d780: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
d790: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
d7a0: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
d7b0: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
d7c0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
d7d0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
d7e0: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
d7f0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
d800: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
d810: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
d820: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
d830: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
d840: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
d850: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
d860: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
d870: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
d880: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
d890: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
d8a0: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
d8b0: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
d8c0: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
d8d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
d8e0: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
d8f0: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
d900: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d910: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
d920: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
d930: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
d940: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d950: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
d960: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
d970: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
d980: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
d990: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
d9a0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
d9b0: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
d9c0: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
d9d0: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
d9e0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
d9f0: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
da00: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
da10: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
da20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
da30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
da40: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
da50: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
da60: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
da70: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
da80: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
da90: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
daa0: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
dab0: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
dac0: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
dad0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
dae0: 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
daf0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
db00: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
db10: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
db20: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
db30: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
db40: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
db50: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
db60: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
db70: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
db80: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
db90: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
dba0: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
dbb0: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
dbc0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
dbd0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
dbe0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
dbf0: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
dc00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
dc10: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
dc20: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
dc30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
dc40: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
dc50: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
dc60: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
dc70: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
dc80: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
dc90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
dca0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
dcb0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
dcc0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
dcd0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
dce0: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
dcf0: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
dd00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
dd10: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
dd20: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
dd30: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
dd40: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
dd50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
dd60: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
dd70: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
dd80: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
dd90: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
dda0: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
ddb0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
ddc0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
ddd0: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
dde0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
ddf0: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
de00: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
de10: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
de20: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
de30: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
de40: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
de50: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
de60: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
de70: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
de80: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
de90: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
dea0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
deb0: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
dec0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
ded0: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
dee0: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
def0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
df00: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
df10: 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
df20: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
df30: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
df40: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
df50: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
df60: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
df70: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
df80: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
df90: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
dfa0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
dfb0: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
dfc0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
dfd0: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
dfe0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
dff0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
e000: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
e010: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e020: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
e030: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
e040: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
e050: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
e060: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
e070: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
e080: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
e090: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
e0a0: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
e0b0: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
e0c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
e0d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
e0e0: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
e0f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
e100: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
e110: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
e120: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
e130: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
e140: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
e150: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
e160: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
e170: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
e180: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
e190: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
e1a0: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
e1b0: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
e1c0: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
e1d0: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
e1e0: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
e1f0: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
e200: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
e210: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
e220: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
e230: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
e240: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
e250: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
e260: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
e270: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
e280: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
e290: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
e2a0: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
e2b0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
e2c0: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
e2d0: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
e2e0: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
e2f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
e300: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
e310: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
e320: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
e330: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
e340: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
e350: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
e360: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
e370: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
e380: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
e390: 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
e3a0: 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
e3b0: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
e3c0: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
e3d0: 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
e3e0: 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
e3f0: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
e400: 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
e410: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
e420: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
e430: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
e440: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
e450: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
e460: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
e470: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
e480: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
e490: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
e4a0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
e4b0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
e4c0: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
e4d0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
e4e0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
e4f0: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
e500: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
e510: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
e520: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
e530: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
e540: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
e550: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
e560: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
e570: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
e580: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
e590: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
e5a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
e5b0: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
e5c0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
e5d0: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
e5e0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
e5f0: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
e600: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
e610: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
e620: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
e630: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
e640: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
e650: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
e660: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
e670: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
e680: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
e690: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
e6a0: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
e6b0: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
e6c0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
e6d0: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
e6e0: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
e6f0: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
e700: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
e710: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
e720: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
e730: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
e740: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
e750: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
e760: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
e770: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
e780: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
e790: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
e7a0: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
e7b0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
e7c0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
e7d0: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
e7e0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
e7f0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
e800: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
e810: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e820: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
e830: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
e840: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
e850: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
e860: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
e870: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
e880: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
e890: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
e8a0: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
e8b0: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
e8c0: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
e8d0: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
e8e0: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
e8f0: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
e900: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
e910: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
e920: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
e930: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
e940: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
e950: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
e960: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
e970: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
e980: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
e990: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
e9a0: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
e9b0: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
e9c0: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
e9d0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
e9e0: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
e9f0: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
ea00: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
ea10: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
ea20: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ea30: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
ea40: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
ea50: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
ea60: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
ea70: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
ea80: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
ea90: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
eaa0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
eab0: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
eac0: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
ead0: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
eae0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
eaf0: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
eb00: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
eb10: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
eb20: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
eb30: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
eb40: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
eb50: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
eb60: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
eb70: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
eb80: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
eb90: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
eba0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
ebb0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
ebc0: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
ebd0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
ebe0: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
ebf0: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
ec00: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
ec10: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
ec20: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
ec30: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
ec40: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
ec50: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
ec60: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
ec70: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
ec80: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
ec90: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
eca0: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
ecb0: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
ecc0: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
ecd0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
ece0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
ecf0: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
ed00: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
ed10: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
ed20: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
ed30: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
ed40: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
ed50: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
ed60: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
ed70: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
ed80: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
ed90: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
eda0: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
edb0: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
edc0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
edd0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
ede0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
edf0: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
ee00: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
ee10: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
ee20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
ee30: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
ee40: 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
ee50: 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
ee60: 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
ee70: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
ee80: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
ee90: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
eea0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
eeb0: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
eec0: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
eed0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
eee0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
eef0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
ef00: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
ef10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
ef20: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
ef30: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
ef40: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
ef50: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
ef60: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
ef70: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
ef80: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
ef90: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
efa0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
efb0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
efc0: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
efd0: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
efe0: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
eff0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
f000: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
f010: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
f020: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
f030: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
f040: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
f050: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
f060: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
f070: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
f080: 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
f090: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
f0a0: 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
f0b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
f0c0: 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
f0d0: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
f0e0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
f0f0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
f100: 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
f110: 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
f120: 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
f130: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
f140: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
f150: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
f160: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
f170: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
f180: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
f190: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
f1a0: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
f1b0: 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
f1c0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
f1d0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
f1e0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
f1f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
f200: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f210: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
f220: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
f230: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
f240: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
f250: 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
f260: 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
f270: 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
f280: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f290: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
f2a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
f2b0: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
f2c0: 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
f2d0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
f2e0: 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
f2f0: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
f300: 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
f310: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
f320: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
f330: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
f340: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
f350: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
f360: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
f370: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
f380: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
f390: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
f3a0: 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
f3b0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
f3c0: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
f3d0: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
f3e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f3f0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
f400: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
f410: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
f420: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
f430: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
f440: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
f450: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
f460: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
f470: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
f480: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
f490: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
f4a0: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
f4b0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
f4c0: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
f4d0: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
f4e0: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
f4f0: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
f500: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
f510: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
f520: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
f530: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
f540: 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
f550: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
f560: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
f570: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f580: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
f590: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
f5a0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
f5b0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
f5c0: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
f5d0: 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
f5e0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
f5f0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
f600: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
f610: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
f620: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
f630: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
f640: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
f650: 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
f660: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
f670: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
f680: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
f690: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
f6a0: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
f6b0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
f6c0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
f6d0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
f6e0: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
f6f0: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
f700: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
f710: 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
f720: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
f730: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
f740: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
f750: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
f760: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
f770: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
f780: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
f790: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
f7a0: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
f7b0: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
f7c0: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
f7d0: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
f7e0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f7f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
f800: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
f810: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
f820: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
f830: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
f840: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f850: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
f860: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
f870: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
f880: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
f890: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
f8a0: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
f8b0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
f8c0: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
f8d0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
f8e0: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
f8f0: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
f900: 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
f910: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f920: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
f930: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
f940: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
f950: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
f960: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
f970: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
f980: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
f990: 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
f9a0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
f9b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
f9c0: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
f9d0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
f9e0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
f9f0: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
fa00: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
fa10: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fa20: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
fa30: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
fa40: 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
fa50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
fa60: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
fa70: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
fa80: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
fa90: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
faa0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
fab0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
fac0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
fad0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
fae0: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
faf0: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
fb00: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
fb10: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
fb20: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
fb30: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
fb40: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
fb50: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
fb60: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
fb70: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
fb80: 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
fb90: 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
fba0: 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
fbb0: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
fbc0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
fbd0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
fbe0: 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
fbf0: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
fc00: 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
fc10: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
fc20: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
fc30: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fc40: 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
fc50: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
fc60: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
fc70: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
fc80: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
fc90: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
fca0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
fcb0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
fcc0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
fcd0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
fce0: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
fcf0: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
fd00: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
fd10: 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
fd20: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
fd30: 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
fd40: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
fd50: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
fd60: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
fd70: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
fd80: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
fd90: 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
fda0: 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
fdb0: 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
fdc0: 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
fdd0: 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
fde0: 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
fdf0: 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
fe00: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
fe10: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fe20: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
fe30: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
fe40: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
fe50: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
fe60: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
fe70: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
fe80: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
fe90: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
fea0: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
feb0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
fec0: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
fed0: 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
fee0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
fef0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
ff00: 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
ff10: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
ff20: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
ff30: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
ff40: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
ff50: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
ff60: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
ff70: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
ff80: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
ff90: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
ffa0: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
ffb0: 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
ffc0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
ffd0: 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
ffe0: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
fff0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
10000 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
10010 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
10020 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
10030 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
10040 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
10050 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
10060 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
10070 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
10080 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
10090 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
100a0 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
100b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
100c0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
100d0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
100e0 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
100f0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
10100 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
10110 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
10120 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
10130 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
10140 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
10150 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
10160 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
10170 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
10180 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
10190 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
101a0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
101b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
101c0 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
101d0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
101e0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
101f0 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
10200 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
10210 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
10220 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
10230 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
10240 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
10250 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
10260 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10270 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
10280 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
10290 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
102a0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
102b0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
102c0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
102d0 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
102e0 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
102f0 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
10300 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
10310 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
10320 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
10330 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
10340 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
10350 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
10360 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
10370 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
10380 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
10390 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
103a0 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
103b0 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
103c0 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
103d0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
103e0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
103f0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
10400 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
10410 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
10420 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
10430 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
10440 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
10450 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
10460 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
10470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
10480 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
10490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
104a0 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
104b0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
104c0 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
104d0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
104e0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
104f0 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
10500 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
10510 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
10520 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
10530 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
10540 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
10550 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
10560 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
10570 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10580 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
10590 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
105a0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
105b0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
105c0 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
105d0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
105e0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
105f0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
10600 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
10610 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
10620 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
10630 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
10640 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
10650 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
10660 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
10670 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
10680 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
10690 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
106a0 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
106b0 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
106c0 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
106d0 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
106e0 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
106f0 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
10700 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
10710 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
10720 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
10730 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
10740 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
10750 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
10760 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
10770 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
10780 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
10790 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
107a0 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
107b0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
107c0 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
107d0 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
107e0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
107f0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
10800 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
10810 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
10820 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
10830 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
10840 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
10850 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
10860 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
10870 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
10880 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
10890 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
108a0 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
108b0 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
108c0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
108d0 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
108e0 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
108f0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
10900 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
10910 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
10920 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f  space..** The po
10930 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
10940 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
10950 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
10960 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
10970 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
10980 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
10990 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
109a0 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
109b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
109c0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
109d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
109e0 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
109f0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
10a00 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
10a10 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
10a20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
10a30 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
10a40 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
10a50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10a60 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
10a70 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
10a80 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
10a90 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
10aa0 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
10ab0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
10ac0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
10ad0 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
10ae0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
10af0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
10b00 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
10b10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
10b20 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
10b30 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
10b40 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
10b50 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
10b60 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
10b70 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
10b80 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
10b90 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
10ba0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
10bb0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
10bc0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
10bd0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
10be0 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
10bf0 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
10c00 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
10c10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10c20 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
10c30 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
10c40 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
10c50 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
10c60 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
10c70 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
10c80 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
10c90 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
10ca0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
10cb0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
10cc0 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
10cd0 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
10ce0 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
10cf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
10d00 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
10d10 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
10d20 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
10d30 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
10d40 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
10d50 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
10d60 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
10d70 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
10d80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
10d90 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
10da0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
10db0 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
10dc0 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
10dd0 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
10de0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
10df0 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
10e00 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
10e10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10e20 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
10e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10e40 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
10e50 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
10e60 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
10e70 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
10e80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
10e90 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
10ea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
10eb0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
10ec0 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
10ed0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
10ee0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
10ef0 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
10f00 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
10f10 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
10f20 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
10f30 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
10f40 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
10f50 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
10f60 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
10f70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
10f80 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
10f90 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
10fa0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
10fb0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
10fc0 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
10fd0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10fe0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10ff0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11000 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11010 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11020 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11030 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
11040 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
11050 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
11060 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
11070 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
11080 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11090 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
110a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
110b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
110c0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
110d0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
110e0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
110f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11100 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
11110 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
11120 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
11130 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11140 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11150 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
11160 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
11170 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
11180 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
11190 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
111a0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
111b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
111c0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
111d0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
111e0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
111f0 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
11200 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
11210 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
11220 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
11230 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
11240 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
11250 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
11260 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
11270 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
11280 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
11290 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
112a0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
112b0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
112c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
112d0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
112e0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
112f0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11300 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11310 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11320 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
11330 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
11340 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
11350 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
11360 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
11370 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11380 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
11390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
113a0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
113b0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
113c0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
113d0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
113e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
113f0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
11400 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11410 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
11420 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
11430 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
11440 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
11450 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
11460 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
11470 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
11480 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
11490 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
114a0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
114b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
114c0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
114d0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
114e0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
114f0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
11500 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
11510 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
11520 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
11530 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
11540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
11550 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
11560 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
11570 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
11580 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
11590 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
115a0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
115b0 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
115c0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
115d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
115e0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
115f0 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
11600 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
11610 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
11620 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11630 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
11640 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
11650 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
11660 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11670 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11680 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
11690 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
116a0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
116b0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
116c0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
116d0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
116e0 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
116f0 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
11700 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
11710 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
11720 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
11730 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
11740 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
11750 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
11760 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
11770 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
11780 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11790 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
117a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
117b0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
117c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
117d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
117e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
117f0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
11800 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
11810 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
11820 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
11830 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
11840 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
11850 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
11860 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
11870 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
11880 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11890 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
118a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
118b0 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
118c0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
118d0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
118e0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
118f0 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
11900 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
11910 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
11920 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
11930 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
11940 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
11950 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
11960 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
11970 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
11980 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
11990 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
119a0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
119b0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
119c0 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
119d0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
119e0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
119f0 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
11a00 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
11a10 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
11a20 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
11a30 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
11a40 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11a50 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
11a60 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
11a70 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
11a80 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
11a90 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
11aa0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
11ab0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
11ac0 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
11ad0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
11ae0 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
11af0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
11b00 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
11b10 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
11b20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
11b30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
11b40 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
11b50 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
11b60 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
11b70 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
11b80 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
11b90 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
11ba0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
11bb0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
11bc0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
11bd0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
11be0 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
11bf0 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
11c00 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
11c10 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
11c20 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
11c30 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
11c40 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
11c50 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
11c60 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
11c70 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
11c80 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
11c90 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
11ca0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
11cb0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
11cc0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
11cd0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
11ce0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
11cf0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
11d00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
11d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
11d20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11d30 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
11d40 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b   This option tak
11d50 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
11d60 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
11d70 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  . If non-zero, t
11d80 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c  hen.** URI handl
11d90 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
11da0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
11db0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
11dc0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
11dd0 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61  ling.** is globa
11de0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66  lly disabled. If
11df0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
11e00 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
11e10 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
11e20 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73  .** passed to [s
11e30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
11e40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
11e50 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
11e60 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
11e70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
11e80 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
11e90 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
11ea0 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
11eb0 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
11ec0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
11ed0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
11ee0 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
11ef0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
11f00 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
11f10 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74  is opened. If it
11f20 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
11f30 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
11f40 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
11f50 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
11f60 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
11f70 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
11f80 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
11f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11fa0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42  ion is opened. B
11fb0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
11fc0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
11fd0 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
11fe0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
11ff0 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
12000 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
12010 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
12020 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
12030 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ol defined..**.*
12040 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12050 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
12060 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
12070 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
12080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
12090 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
120a0 4e 46 4e 49 47 5f 47 45 54 50 43 41 43 48 45 0a  NFNIG_GETPCACHE.
120b0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
120c0 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
120d0 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
120e0 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
120f0 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
12100 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
12110 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
12120 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
12130 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
12140 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
12150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
12160 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
12170 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
12180 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12190 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
121a0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
121b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
121c0 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
121d0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
121e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
121f0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
12200 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
12210 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
12220 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12230 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
12240 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
12250 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
12260 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12270 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
12280 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
12290 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
122a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
122b0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
122c0 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
122d0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
122e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
122f0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
12300 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
12310 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
12320 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
12330 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12340 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
12350 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
12360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12370 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
12380 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
12390 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
123a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
123b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
123c0 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
123d0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
123e0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
123f0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
12400 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
12410 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
12420 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
12430 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12440 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
12450 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
12460 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12470 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
12480 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
12490 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
124a0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
124b0 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
124c0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
124d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
124e0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
124f0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
12500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12510 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
12520 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
12530 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12540 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
12550 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
12560 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
12570 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
12580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
12590 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
125a0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
125b0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a  ethods2* */../*.
125c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
125d0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
125e0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
125f0 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
12600 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
12610 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
12620 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
12630 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
12640 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
12650 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
12660 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
12670 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
12680 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
12690 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
126a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
126b0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
126c0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
126d0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
126e0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
126f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
12700 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
12710 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
12720 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
12730 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
12740 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
12750 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
12760 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
12770 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
12780 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
12790 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
127a0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
127b0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
127c0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
127d0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
127e0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
127f0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
12800 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
12810 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
12820 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
12830 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
12840 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
12850 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
12860 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
12870 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
12880 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
12890 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
128a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
128b0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
128c0 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
128d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
128e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
128f0 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
12900 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
12910 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12920 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
12930 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
12940 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
12950 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
12960 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
12970 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
12980 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
12990 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
129a0 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
129b0 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
129c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
129d0 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
129e0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
129f0 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
12a00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
12a10 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
12a20 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
12a30 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
12a40 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
12a50 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
12a60 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
12a70 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
12a80 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
12a90 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
12aa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12ab0 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
12ac0 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
12ad0 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
12ae0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
12af0 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
12b00 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
12b10 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
12b20 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
12b30 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
12b40 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12b50 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
12b60 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12b70 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
12b80 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
12b90 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
12ba0 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
12bb0 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
12bc0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
12bd0 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
12be0 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
12bf0 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
12c00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12c10 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
12c20 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
12c30 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
12c40 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
12c50 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
12c60 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
12c70 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
12c80 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
12c90 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
12ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
12cb0 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
12cc0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
12cd0 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
12ce0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
12cf0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
12d00 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
12d10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
12d20 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
12d30 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
12d40 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
12d50 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
12d60 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
12d70 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
12d80 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
12d90 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
12da0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
12db0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
12dc0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
12dd0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
12de0 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
12df0 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
12e00 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
12e10 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
12e20 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
12e30 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
12e40 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
12e50 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
12e60 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
12e70 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
12e80 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
12e90 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
12ea0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
12eb0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
12ec0 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
12ed0 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
12ee0 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
12ef0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
12f00 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
12f10 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
12f20 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
12f30 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
12f40 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
12f50 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
12f60 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
12f70 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
12f80 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12f90 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
12fa0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
12fb0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
12fc0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
12fd0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
12fe0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
12ff0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
13000 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
13010 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
13020 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
13030 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
13040 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
13050 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
13060 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
13070 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
13080 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
13090 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
130a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
130b0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
130c0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
130d0 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
130e0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
130f0 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
13100 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
13110 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
13120 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
13130 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13140 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
13150 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
13160 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
13170 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
13180 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
13190 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
131a0 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
131b0 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
131c0 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
131d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
131e0 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
131f0 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
13200 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
13210 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
13220 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
13230 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  . </dd>.**.** </
13240 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
13250 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
13260 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31  OOKASIDE       1
13270 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
13280 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
13290 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
132a0 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20  _ENABLE_FKEY    
132b0 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e   1002  /* int in
132c0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
132d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
132e0 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30  ABLE_TRIGGER  10
132f0 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  03  /* int int* 
13300 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
13310 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
13320 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
13330 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a  Result Codes.**.
13340 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
13350 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
13360 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
13370 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
13380 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
13390 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
133a0 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
133b0 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
133c0 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
133d0 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
133e0 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
133f0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
13400 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
13410 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
13420 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
13430 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
13440 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
13450 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
13460 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45  t Rowid.**.** ^E
13470 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
13480 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
13490 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
134a0 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
134b0 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
134c0 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
134d0 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
134e0 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
134f0 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
13500 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
13510 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
13520 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
13530 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
13540 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
13550 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
13560 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
13570 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
13580 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
13590 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
135a0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
135b0 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
135c0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
135d0 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
135e0 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
135f0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
13600 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
13610 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
13620 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
13630 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74   [INSERT] into t
13640 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
13650 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
13660 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  onnection].** in
13670 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13680 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c  ent.  ^As of SQL
13690 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
136a0 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73  7, this routines
136b0 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20  .** records the 
136c0 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
136d0 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61  d of both ordina
136e0 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76  ry tables and [v
136f0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a  irtual tables]..
13700 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  ** ^If no succes
13710 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a  sful [INSERT]s.*
13720 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
13730 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
13740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13750 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
13760 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ed..**.** ^(If a
13770 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
13780 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
13790 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
137a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
137b0 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
137c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
137d0 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
137e0 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
137f0 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
13800 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
13810 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
13820 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
13830 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
13840 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
13850 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
13860 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
13870 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
13880 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
13890 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
138a0 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
138b0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
138c0 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
138d0 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
138e0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
138f0 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
13900 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
13910 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
13920 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
13930 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
13940 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
13950 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
13960 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
13970 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
13980 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
13990 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
139a0 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
139b0 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
139c0 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
139d0 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
139e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
139f0 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
13a00 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
13a10 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
13a20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
13a30 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
13a40 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
13a50 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
13a60 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
13a70 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
13a80 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
13a90 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
13aa0 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
13ab0 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
13ac0 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
13ad0 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
13ae0 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
13af0 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
13b00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
13b10 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
13b20 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
13b30 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
13b40 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
13b50 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
13b60 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
13b70 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
13b80 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
13b90 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
13ba0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
13bb0 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
13bc0 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
13bd0 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
13be0 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
13bf0 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
13c00 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
13c10 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
13c20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
13c30 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
13c40 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
13c50 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
13c60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
13c70 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
13c80 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
13c90 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
13ca0 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
13cb0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
13cc0 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
13cd0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
13ce0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
13cf0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
13d00 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
13d10 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
13d20 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
13d30 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
13d40 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
13d50 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
13d60 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
13d70 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
13d80 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
13d90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13da0 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
13db0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
13dc0 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
13dd0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
13de0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
13df0 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
13e00 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
13e10 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
13e20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
13e30 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
13e40 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
13e50 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
13e60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13e70 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
13e80 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
13e90 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
13ea0 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
13eb0 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
13ec0 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
13ed0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
13ee0 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
13ef0 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
13f00 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
13f10 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
13f20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
13f30 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
13f40 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
13f50 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
13f60 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
13f70 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
13f80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
13f90 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
13fa0 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
13fb0 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
13fc0 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
13fd0 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
13fe0 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
13ff0 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
14000 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
14010 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
14020 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
14030 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
14040 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
14050 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
14060 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
14070 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
14080 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
14090 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
140a0 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
140b0 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
140c0 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
140d0 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
140e0 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
140f0 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
14100 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
14110 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
14120 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
14130 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
14140 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
14150 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
14160 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
14170 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
14180 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
14190 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
141a0 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
141b0 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
141c0 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
141d0 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
141e0 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
141f0 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
14200 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
14210 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
14220 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
14230 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
14240 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
14250 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
14260 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
14270 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
14280 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
14290 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
142a0 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
142b0 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
142c0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
142d0 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
142e0 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
142f0 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
14300 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
14310 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
14320 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
14330 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
14340 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
14350 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
14360 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
14370 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
14380 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
14390 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
143a0 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
143b0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
143c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
143d0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
143e0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
143f0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
14400 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
14410 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
14420 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
14430 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
14440 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
14450 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
14460 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
14470 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
14480 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
14490 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
144a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
144b0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
144c0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
144d0 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
144e0 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
144f0 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
14500 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
14510 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
14520 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
14530 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
14540 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
14550 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
14560 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
14570 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
14580 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
14590 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
145a0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
145b0 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
145c0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
145d0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
145e0 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
145f0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
14600 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
14610 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
14620 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
14630 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
14640 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
14650 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
14660 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
14670 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
14680 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
14690 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
146a0 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
146b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
146c0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
146d0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
146e0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
146f0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
14700 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
14710 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
14720 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
14730 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
14740 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
14750 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
14760 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
14770 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
14780 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
14790 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
147a0 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
147b0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
147c0 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
147d0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
147e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
147f0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
14800 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20  by [INSERT],.** 
14810 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
14820 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
14830 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
14840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14850 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e  was opened..** ^
14860 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72  (The count retur
14870 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
14880 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69  otal_changes() i
14890 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
148a0 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20  ges.** from all 
148b0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
148c0 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65  | trigger] conte
148d0 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20  xts and changes 
148e0 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65  made by.** [fore
148f0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
14900 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68  . However,.** th
14910 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  e count does not
14920 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
14930 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
14940 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  nt [REPLACE] con
14950 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
14960 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
14970 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
14980 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70  r [DROP TABLE] p
14990 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a  rocessing.  The.
149a0 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  ** count does no
149b0 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f  t include rows o
149c0 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72  f views that fir
149d0 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  e an [INSTEAD OF
149e0 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68   trigger],.** th
149f0 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54  ough if the INST
14a00 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d  EAD OF trigger m
14a10 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20  akes changes of 
14a20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63  its own, those c
14a30 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63  hanges .** are c
14a40 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68  ounted.)^.** ^Th
14a50 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  e sqlite3_total_
14a60 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
14a70 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68  on counts the ch
14a80 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73  anges as soon as
14a90 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
14aa0 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
14ab0 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28  m is completed (
14ac0 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
14ad0 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  nt handle.** is 
14ae0 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
14af0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
14b00 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
14b10 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
14b20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
14b30 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
14b40 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
14b50 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
14b60 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
14b70 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
14b80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
14b90 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
14ba0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
14bb0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
14bc0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
14bd0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
14be0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
14bf0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
14c00 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
14c10 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
14c20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
14c30 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
14c40 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
14c50 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
14c60 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
14c70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
14c80 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
14c90 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
14ca0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
14cb0 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
14cc0 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
14cd0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
14ce0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
14cf0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
14d00 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
14d10 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
14d20 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
14d30 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
14d40 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
14d50 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
14d60 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
14d70 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
14d80 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
14d90 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
14da0 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
14db0 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
14dc0 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
14dd0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
14de0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
14df0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
14e00 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
14e10 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
14e20 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
14e30 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
14e40 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
14e50 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
14e60 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
14e70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14e80 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
14e90 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
14ea0 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
14eb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14ec0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
14ed0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
14ee0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
14ef0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
14f00 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
14f10 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
14f20 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
14f30 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
14f40 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
14f50 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
14f60 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
14f70 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
14f80 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
14f90 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
14fa0 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
14fb0 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
14fc0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
14fd0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
14fe0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
14ff0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
15000 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
15010 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
15020 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
15030 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
15040 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
15050 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
15060 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
15070 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
15080 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
15090 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
150a0 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
150b0 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
150c0 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
150d0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
150e0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
150f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15100 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
15110 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
15120 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
15130 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
15140 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
15150 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
15160 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
15170 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
15180 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
15190 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
151a0 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
151b0 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
151c0 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
151d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
151e0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
151f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
15200 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
15210 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
15220 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
15230 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
15240 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
15250 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
15260 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
15270 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
15280 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
15290 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
152a0 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
152b0 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
152c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
152d0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
152e0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
152f0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
15300 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
15310 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
15320 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
15330 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
15340 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
15350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
15360 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
15370 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
15380 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
15390 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
153a0 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
153b0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
153c0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
153d0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
153e0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
153f0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
15400 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
15410 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
15420 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
15430 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
15440 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
15450 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
15460 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
15470 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
15480 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
15490 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
154a0 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
154b0 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
154c0 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
154d0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
154e0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
154f0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
15500 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
15510 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
15520 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
15530 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
15540 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
15550 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
15560 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
15570 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
15580 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
15590 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
155a0 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
155b0 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
155c0 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
155d0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
155e0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
155f0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
15600 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
15610 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
15620 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
15630 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
15640 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
15650 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
15660 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
15670 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
15680 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
15690 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
156a0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
156b0 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
156c0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
156d0 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
156e0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
156f0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
15700 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
15710 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
15720 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
15730 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
15740 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
15750 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
15760 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
15770 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
15780 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
15790 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
157a0 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
157b0 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
157c0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
157d0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
157e0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
157f0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
15800 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
15810 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
15820 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
15830 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
15840 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
15850 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
15860 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
15870 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
15880 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
15890 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
158a0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
158b0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
158c0 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
158d0 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
158e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
158f0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
15900 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
15910 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
15920 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
15930 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
15940 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
15950 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
15960 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
15970 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
15980 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
15990 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
159a0 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
159b0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
159c0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
159d0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
159e0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
159f0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
15a00 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
15a10 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
15a20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
15a30 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
15a40 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
15a50 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
15a60 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
15a70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15a80 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
15a90 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
15aa0 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
15ab0 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  rors.**.** ^This
15ac0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
15ad0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
15ae0 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
15af0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
15b00 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
15b10 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
15b20 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
15b30 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
15b40 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
15b50 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
15b60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
15b70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
15b80 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
15b90 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
15ba0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
15bb0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
15bc0 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
15bd0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
15be0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
15bf0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
15c00 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
15c10 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
15c20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
15c30 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
15c40 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
15c50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
15c60 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
15c70 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
15c80 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
15c90 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
15ca0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
15cb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
15cc0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
15cd0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15ce0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
15cf0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
15d00 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
15d10 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
15d20 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
15d30 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
15d40 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
15d50 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
15d60 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
15d70 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
15d80 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
15d90 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
15da0 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
15db0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
15dc0 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
15dd0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
15de0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
15df0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  turned..** ^If t
15e00 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
15e10 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
15e20 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
15e30 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
15e40 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
15e50 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
15e60 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
15e70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
15e80 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
15e90 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
15ea0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
15eb0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
15ec0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
15ed0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
15ee0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
15ef0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
15f00 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
15f10 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
15f20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
15f30 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
15f40 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
15f50 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
15f60 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
15f70 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
15f80 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
15f90 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
15fa0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
15fb0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
15fc0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
15fd0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
15fe0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
15ff0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
16000 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
16010 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
16020 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
16030 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
16040 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
16050 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
16060 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
16070 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
16080 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
16090 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
160a0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
160b0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
160c0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
160d0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
160e0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
160f0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
16100 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
16110 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
16120 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
16130 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
16140 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
16150 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
16160 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
16170 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
16180 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
16190 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
161a0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
161b0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
161c0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
161d0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
161e0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
161f0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
16200 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
16210 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
16220 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
16230 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
16240 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
16250 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
16260 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
16270 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
16280 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
16290 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
162a0 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
162b0 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
162c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
162d0 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
162e0 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
162f0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
16300 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
16310 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
16320 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
16330 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
16340 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
16350 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
16360 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
16370 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
16380 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
16390 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
163a0 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
163b0 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
163c0 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
163d0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
163e0 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e  s.  ^If it is un
163f0 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
16400 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
16410 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
16420 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
16430 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
16440 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
16450 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
16460 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
16470 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
16480 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
16490 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
164a0 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
164b0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
164c0 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65  OCKED].  ^This e
164d0 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
164e0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
164f0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
16500 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
16510 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
16520 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
16530 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
16540 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
16550 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
16560 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
16570 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
16580 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
16590 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
165a0 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
165b0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  nt..**.** ^(Ther
165c0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
165d0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
165e0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
165f0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
16600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
16610 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
16620 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
16630 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
16640 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
16650 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
16660 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
16670 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
16680 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
16690 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
166a0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
166b0 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
166c0 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
166d0 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
166e0 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
166f0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
16700 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
16710 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
16720 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
16730 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
16740 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
16750 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
16760 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
16770 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
16780 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
16790 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
167a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
167b0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
167c0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
167d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
167e0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
167f0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
16800 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
16810 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16820 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
16830 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
16840 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
16850 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
16860 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
16870 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
16880 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
16890 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
168a0 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
168b0 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
168c0 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
168d0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
168e0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
168f0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
16900 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
16910 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
16920 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
16930 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
16940 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
16950 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
16960 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
16970 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
16980 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16990 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
169a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
169b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
169c0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
169d0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
169e0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
169f0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
16a00 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
16a10 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
16a20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
16a30 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
16a40 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
16a50 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
16a60 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
16a70 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
16a80 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
16a90 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
16aa0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
16ab0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
16ac0 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
16ad0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
16ae0 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
16af0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
16b00 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
16b10 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
16b20 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
16b30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
16b40 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
16b50 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
16b60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16b70 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
16b80 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
16b90 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
16ba0 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
16bb0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
16bc0 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
16bd0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
16be0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
16bf0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
16c00 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
16c10 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
16c20 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
16c30 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
16c40 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
16c50 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
16c60 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
16c70 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
16c80 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
16c90 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
16ca0 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
16cb0 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
16cc0 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
16cd0 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
16ce0 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
16cf0 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
16d00 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
16d10 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
16d20 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
16d30 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
16d40 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
16d50 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
16d60 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
16d70 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
16d80 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
16d90 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
16da0 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
16db0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
16dc0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
16dd0 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
16de0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
16df0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
16e00 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
16e10 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
16e20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
16e30 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
16e40 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
16e50 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
16e60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16e70 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
16e80 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
16e90 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
16ea0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
16eb0 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
16ec0 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
16ed0 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
16ee0 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
16ef0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
16f00 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
16f10 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
16f20 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
16f30 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
16f40 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
16f50 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
16f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
16f70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
16f80 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
16f90 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
16fa0 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
16fb0 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
16fc0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
16fd0 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
16fe0 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
16ff0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
17000 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
17010 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
17020 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
17030 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
17040 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
17050 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
17060 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
17070 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
17080 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
17090 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
170a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
170b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
170c0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
170d0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
170e0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
170f0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
17100 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
17110 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
17120 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
17130 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
17140 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
17150 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
17160 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
17170 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
17180 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
17190 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
171a0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
171b0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
171c0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
171d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
171e0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
171f0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
17200 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
17210 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
17220 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
17230 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
17240 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
17250 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
17260 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
17270 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
17280 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
17290 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
172a0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
172b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
172c0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
172d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
172e0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
172f0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
17300 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
17310 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
17320 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
17330 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
17340 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
17350 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
17360 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
17370 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
17380 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
17390 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
173a0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
173b0 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
173c0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
173d0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
173e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
173f0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
17400 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
17410 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
17420 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
17430 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
17440 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
17450 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
17460 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
17470 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
17480 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
17490 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
174a0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
174b0 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
174c0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
174d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
174e0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
174f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
17500 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
17510 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
17520 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
17530 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
17540 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17550 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
17560 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
17570 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
17580 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
17590 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
175a0 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
175b0 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
175c0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
175d0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
175e0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
175f0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
17600 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
17610 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
17620 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
17630 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
17640 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
17650 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
17660 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
17670 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
17680 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
17690 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
176a0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
176b0 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
176c0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
176d0 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
176e0 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
176f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
17700 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
17710 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
17720 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
17730 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
17740 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
17750 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
17760 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
17770 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
17780 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
17790 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
177a0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
177b0 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
177c0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
177d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
177e0 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
177f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
17800 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
17810 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
17820 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
17830 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
17840 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
17850 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
17860 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
17870 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
17880 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
17890 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
178a0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
178b0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
178c0 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
178d0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
178e0 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
178f0 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
17900 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
17910 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
17920 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
17930 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
17940 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
17950 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
17960 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17970 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
17980 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
17990 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
179a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
179b0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
179c0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
179d0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
179e0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
179f0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
17a00 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
17a10 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
17a20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
17a30 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
17a40 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
17a50 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
17a60 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
17a70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17a80 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
17a90 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
17aa0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
17ab0 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
17ac0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
17ad0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
17ae0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
17af0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
17b00 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
17b10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
17b20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
17b30 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
17b40 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
17b50 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
17b60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
17b70 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
17b80 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
17b90 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
17ba0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
17bb0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
17bc0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
17bd0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
17be0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
17bf0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
17c00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
17c10 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
17c20 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
17c30 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
17c40 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
17c50 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
17c60 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
17c70 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
17c80 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
17c90 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
17ca0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
17cb0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
17cc0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
17cd0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
17ce0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
17cf0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
17d00 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
17d10 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
17d20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
17d30 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
17d40 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
17d50 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
17d60 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
17d70 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
17d80 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
17d90 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
17da0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
17db0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
17dc0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
17dd0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
17de0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
17df0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
17e00 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
17e10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
17e20 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
17e30 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
17e40 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
17e50 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
17e60 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
17e70 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
17e80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
17e90 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
17ea0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
17eb0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
17ec0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
17ed0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
17ee0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
17ef0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
17f00 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
17f10 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
17f20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
17f30 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
17f40 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
17f50 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
17f60 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
17f70 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
17f80 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
17f90 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
17fa0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
17fb0 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
17fc0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
17fd0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
17fe0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
17ff0 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
18000 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
18010 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
18020 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
18030 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
18040 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
18050 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
18060 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
18070 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
18080 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
18090 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
180a0 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
180b0 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
180c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
180d0 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
180e0 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
180f0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
18100 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
18110 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
18120 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
18130 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
18140 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
18150 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
18160 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
18170 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
18180 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
18190 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
181a0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
181b0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
181c0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
181d0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
181e0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
181f0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
18200 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
18210 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
18220 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
18230 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
18240 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
18250 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18260 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
18270 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
18280 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
18290 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
182a0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
182b0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
182c0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
182d0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
182e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
182f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
18300 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
18310 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
18320 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
18330 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
18340 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
18350 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
18360 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
18370 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
18380 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
18390 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
183a0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
183b0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
183c0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
183d0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
183e0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
183f0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
18400 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
18410 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
18420 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
18430 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
18440 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
18450 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
18460 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
18470 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
18480 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
18490 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
184a0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
184b0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
184c0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
184d0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
184e0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
184f0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
18500 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
18510 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
18520 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
18530 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18540 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
18550 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
18560 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
18570 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
18580 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
18590 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
185a0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
185b0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
185c0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
185d0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
185e0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
185f0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
18600 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
18610 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
18620 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
18630 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
18640 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
18650 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
18660 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
18670 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
18680 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
18690 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
186a0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
186b0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
186c0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
186d0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
186e0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
186f0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
18700 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18710 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
18720 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
18730 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
18740 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
18750 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
18760 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
18770 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
18780 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
18790 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
187a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
187b0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
187c0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
187d0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
187e0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
187f0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
18800 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
18810 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
18820 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
18830 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
18840 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
18850 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
18860 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
18870 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
18880 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
18890 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
188a0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
188b0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
188c0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
188d0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
188e0 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
188f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
18900 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
18910 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
18920 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
18930 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
18940 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
18950 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
18960 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
18970 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  r*, ...);.char *
18980 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
18990 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
189a0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
189b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
189c0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
189d0 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
189e0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
189f0 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
18a00 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
18a10 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
18a20 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
18a30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18a40 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
18a50 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
18a60 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
18a70 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
18a80 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
18a90 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
18aa0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
18ab0 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
18ac0 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
18ad0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
18ae0 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
18af0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
18b00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
18b10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
18b20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
18b30 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
18b40 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
18b50 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
18b60 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
18b70 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
18b80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
18b90 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
18ba0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
18bb0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
18bc0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
18bd0 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
18be0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
18bf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
18c00 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
18c10 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
18c20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
18c30 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
18c40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
18c50 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
18c60 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
18c70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
18c80 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
18c90 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
18ca0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
18cb0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
18cc0 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
18cd0 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
18ce0 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
18cf0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
18d00 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
18d10 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
18d20 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
18d30 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
18d40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
18d50 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
18d60 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
18d70 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
18d80 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
18d90 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
18da0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
18db0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
18dc0 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
18dd0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
18de0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
18df0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
18e00 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
18e10 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
18e20 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
18e30 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
18e40 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
18e50 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
18e60 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
18e70 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
18e80 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
18e90 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
18ea0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
18eb0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
18ec0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
18ed0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
18ee0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
18ef0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18f00 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
18f10 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
18f20 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
18f30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
18f40 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
18f50 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
18f60 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
18f70 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
18f80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
18f90 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
18fa0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
18fb0 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
18fc0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
18fd0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
18fe0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
18ff0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
19000 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
19010 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
19020 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
19030 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
19040 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
19050 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
19060 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19070 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
19080 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
19090 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
190a0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
190b0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
190c0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
190d0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
190e0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
190f0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
19100 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
19110 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
19120 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19130 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
19140 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
19150 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
19160 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
19170 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
19180 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
19190 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
191a0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
191b0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
191c0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
191d0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
191e0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
191f0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
19200 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
19210 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
19220 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
19230 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
19240 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
19250 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
19260 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
19270 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
19280 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
19290 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
192a0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
192b0 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
192c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
192d0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
192e0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
192f0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
19300 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
19310 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
19320 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
19330 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
19340 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
19350 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
19360 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
19370 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
19380 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
19390 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
193a0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
193b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
193c0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
193d0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
193e0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
193f0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
19400 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
19410 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
19420 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
19430 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
19440 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
19450 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
19460 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
19470 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
19480 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
19490 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
194a0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
194b0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
194c0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
194d0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
194e0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
194f0 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
19500 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
19510 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
19520 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
19530 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
19540 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
19550 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
19560 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
19570 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
19580 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
19590 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
195a0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
195b0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
195c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
195d0 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
195e0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
195f0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
19600 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
19610 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
19620 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
19630 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
19640 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
19650 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
19660 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
19670 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
19680 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
19690 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
196a0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
196b0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
196c0 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
196d0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
196e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
196f0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
19700 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
19710 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
19720 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
19730 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
19740 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
19750 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
19760 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
19770 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
19780 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
19790 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
197a0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
197b0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
197c0 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
197d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
197e0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
197f0 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
19800 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
19810 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
19820 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19830 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
19840 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
19850 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
19860 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
19870 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
19880 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
19890 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
198a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
198b0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
198c0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
198d0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
198e0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
198f0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
19900 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19910 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
19920 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
19930 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
19940 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
19950 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
19960 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
19970 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
19980 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
19990 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
199a0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
199b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
199c0 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
199d0 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
199e0 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
199f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
19a00 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
19a10 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
19a20 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
19a30 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
19a40 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
19a50 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
19a60 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
19a70 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
19a80 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
19a90 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
19aa0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
19ab0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
19ac0 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
19ad0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
19ae0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
19af0 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
19b00 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
19b10 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
19b20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
19b30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19b40 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
19b50 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
19b60 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
19b70 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
19b80 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
19b90 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
19ba0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
19bb0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
19bc0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
19bd0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
19be0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
19bf0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
19c00 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
19c10 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
19c20 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
19c30 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
19c40 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
19c50 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
19c60 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
19c70 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
19c80 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
19c90 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
19ca0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
19cb0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
19cc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
19cd0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
19ce0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
19cf0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
19d00 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
19d10 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
19d20 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
19d30 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
19d40 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
19d50 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
19d60 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
19d70 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
19d80 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
19d90 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
19da0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
19db0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
19dc0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
19dd0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
19de0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
19df0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
19e00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
19e10 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
19e20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
19e30 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
19e40 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
19e50 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
19e60 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
19e70 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
19e80 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
19e90 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
19ea0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
19eb0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
19ec0 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
19ed0 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
19ee0 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
19ef0 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
19f00 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
19f10 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
19f20 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
19f30 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
19f40 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
19f50 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
19f60 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
19f70 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
19f80 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
19f90 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
19fa0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
19fb0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
19fc0 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
19fd0 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
19fe0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
19ff0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1a000 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1a010 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
1a020 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1a030 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1a040 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1a050 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1a060 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1a070 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1a080 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1a090 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a0a0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1a0b0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1a0c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1a0d0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1a0e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1a0f0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1a100 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1a110 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1a120 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1a130 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1a140 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1a150 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1a160 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1a170 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1a180 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1a190 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1a1a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1a1b0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1a1c0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1a1d0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1a1e0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1a1f0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1a200 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1a210 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1a220 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1a230 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1a240 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1a250 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1a260 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1a270 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1a280 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1a290 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1a2a0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1a2b0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1a2c0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1a2d0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1a2e0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1a2f0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1a300 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1a310 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1a320 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1a330 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1a340 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1a350 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1a360 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1a370 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1a380 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1a390 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1a3a0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1a3b0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1a3c0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1a3d0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1a3e0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1a3f0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1a400 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1a410 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1a420 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1a430 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1a440 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1a450 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1a460 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1a470 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1a480 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1a490 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1a4a0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1a4b0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1a4c0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1a4d0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1a4e0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1a4f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a500 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1a510 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1a520 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1a530 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1a540 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1a550 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1a560 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1a570 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1a580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1a590 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a5a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a5b0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1a5c0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1a5d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a5e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1a5f0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1a600 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1a610 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1a620 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1a630 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1a640 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1a650 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1a660 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1a670 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1a680 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1a690 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1a6a0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1a6b0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1a6c0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1a6d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a6e0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1a6f0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1a700 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1a710 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1a720 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1a730 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1a740 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1a750 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1a760 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a770 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1a780 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1a790 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a7a0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1a7b0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1a7c0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1a7d0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1a7e0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1a7f0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1a800 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1a810 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1a820 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1a830 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1a840 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1a850 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1a860 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1a870 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1a880 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1a890 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1a8a0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1a8b0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1a8c0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1a8d0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1a8e0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1a8f0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1a900 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1a910 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1a920 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1a930 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1a940 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1a950 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1a960 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1a970 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1a980 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1a990 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1a9a0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1a9b0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1a9c0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1a9d0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1a9e0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1a9f0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1aa00 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1aa10 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1aa20 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1aa30 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1aa40 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1aa50 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1aa60 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1aa70 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1aa80 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1aa90 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1aaa0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1aab0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1aac0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1aad0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1aae0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1aaf0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1ab00 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1ab10 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1ab20 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1ab30 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1ab40 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1ab50 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1ab60 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1ab70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1ab80 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1ab90 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1aba0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1abb0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1abc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1abd0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1abe0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1abf0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1ac00 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1ac10 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1ac20 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1ac30 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1ac40 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1ac50 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1ac60 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1ac70 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1ac80 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1ac90 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1aca0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1acb0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1acc0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1acd0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1ace0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1acf0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1ad00 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1ad10 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1ad20 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1ad30 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1ad40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ad50 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1ad60 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1ad70 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1ad80 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1ad90 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1ada0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1adb0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1adc0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1add0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1ade0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1adf0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1ae00 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1ae10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ae20 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1ae30 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1ae40 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1ae50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1ae60 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1ae70 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1ae80 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1ae90 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1aea0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1aeb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1aec0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1aed0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1aee0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1aef0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1af00 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1af10 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1af20 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1af30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1af40 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1af50 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1af60 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1af70 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1af80 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1af90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1afa0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1afb0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1afc0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1afd0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1afe0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1aff0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1b000 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1b010 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1b020 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1b030 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1b040 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1b050 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b060 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1b070 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1b080 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1b090 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1b0a0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1b0b0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1b0c0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1b0d0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1b0e0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1b0f0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1b100 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1b110 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1b120 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1b130 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1b140 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1b150 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1b160 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1b170 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1b180 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1b190 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1b1a0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1b1b0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1b1c0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1b1d0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1b1e0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1b1f0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1b200 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1b210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1b220 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1b230 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1b240 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1b250 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1b260 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1b270 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1b280 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1b290 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1b2a0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1b2b0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1b2c0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1b2d0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1b2e0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1b2f0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1b300 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1b310 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1b320 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1b330 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1b340 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1b350 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1b360 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1b370 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1b380 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1b390 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1b3a0 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1b3b0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1b3c0 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1b3d0 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1b3e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1b3f0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1b400 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1b410 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1b420 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1b430 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1b440 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1b450 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1b460 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1b470 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1b480 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1b490 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1b4a0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1b4b0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1b4c0 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1b4d0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1b4e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1b4f0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1b500 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1b510 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1b520 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1b530 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1b540 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1b550 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1b560 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1b570 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1b580 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1b590 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1b5a0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1b5b0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1b5c0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1b5d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b5e0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1b5f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1b600 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1b610 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1b620 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1b630 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1b640 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1b650 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1b660 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1b670 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1b680 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1b690 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1b6a0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1b6b0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1b6c0 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1b6d0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1b6e0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1b6f0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1b700 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1b710 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1b720 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1b730 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1b740 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1b750 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1b760 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1b770 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1b780 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b790 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1b7a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1b7b0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1b7c0 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1b7d0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1b7e0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1b7f0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1b800 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1b810 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1b820 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1b830 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1b840 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1b850 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b860 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1b870 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1b880 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1b890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1b8a0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1b8b0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1b8c0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1b8d0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1b8e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1b8f0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1b900 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1b910 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1b920 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b930 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1b940 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1b950 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1b960 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1b970 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1b980 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b990 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1b9a0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1b9b0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1b9c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b9d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1b9e0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1b9f0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1ba00 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1ba10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ba20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ba30 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1ba40 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1ba50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ba60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ba70 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ba80 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1ba90 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1baa0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1bab0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1bac0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1bad0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1bae0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1baf0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1bb00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1bb10 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1bb20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1bb30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bb40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1bb50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bb60 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1bb70 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1bb80 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1bb90 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1bba0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1bbb0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1bbc0 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1bbd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1bbe0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1bbf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1bc00 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1bc10 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1bc20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1bc30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1bc40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1bc50 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1bc60 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1bc70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1bc80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1bc90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bca0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1bcb0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1bcc0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1bcd0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1bce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bcf0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1bd00 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1bd10 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1bd20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1bd30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bd40 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1bd50 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1bd60 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1bd70 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1bd80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1bd90 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1bda0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1bdb0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1bdc0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1bdd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1bde0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1bdf0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1be00 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1be10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1be20 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1be30 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1be40 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1be50 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1be60 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1be70 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1be80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1be90 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1bea0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1beb0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1bec0 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1bed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1bee0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1bef0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1bf00 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1bf10 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1bf20 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1bf30 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1bf40 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1bf50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1bf60 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1bf70 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1bf80 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1bf90 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1bfa0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1bfb0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1bfc0 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1bfd0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1bfe0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1bff0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c000 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1c010 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1c020 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1c030 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c040 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c050 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1c060 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1c070 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1c080 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1c090 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c0a0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1c0b0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1c0c0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1c0d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c0e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c0f0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1c100 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1c110 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c120 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c140 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1c150 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1c160 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1c170 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1c180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c190 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1c1a0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1c1b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1c1c0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1c1d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c1e0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1c1f0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1c200 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1c210 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1c220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1c230 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1c240 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1c250 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1c260 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1c270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1c280 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1c290 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1c2a0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
1c2b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
1c2c0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
1c2d0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1c2e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1c2f0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
1c300 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1c310 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
1c320 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
1c330 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
1c340 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
1c350 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1c360 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1c370 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1c380 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1c390 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1c3a0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1c3b0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1c3c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1c3d0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1c3e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1c3f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c400 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1c410 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
1c420 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1c430 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
1c440 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1c450 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
1c460 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
1c470 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
1c480 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
1c490 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1c4a0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
1c4b0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1c4c0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1c4d0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1c4e0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1c4f0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1c500 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1c510 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1c520 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1c530 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
1c540 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c550 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1c560 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1c570 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1c580 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
1c590 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
1c5a0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1c5b0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
1c5c0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
1c5d0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1c5e0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
1c5f0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
1c600 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
1c610 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1c620 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
1c630 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1c640 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
1c650 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
1c660 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
1c670 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
1c680 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
1c690 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
1c6a0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
1c6b0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
1c6c0 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
1c6d0 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
1c6e0 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
1c6f0 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
1c700 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1c710 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
1c720 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
1c730 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
1c740 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
1c750 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
1c760 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
1c770 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
1c780 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1c790 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
1c7a0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
1c7b0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
1c7c0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1c7d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1c7e0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1c7f0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1c800 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1c810 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
1c820 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1c830 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
1c840 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
1c850 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
1c860 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1c870 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
1c880 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1c890 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
1c8a0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
1c8b0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
1c8c0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1c8d0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
1c8e0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1c8f0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
1c900 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
1c910 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
1c920 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1c930 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
1c940 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1c950 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1c960 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
1c970 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c980 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
1c990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c9a0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
1c9b0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1c9c0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1c9d0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1c9e0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1c9f0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
1ca00 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
1ca10 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1ca20 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
1ca30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
1ca40 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1ca50 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
1ca60 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
1ca70 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1ca80 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1ca90 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1caa0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1cab0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1cac0 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1cad0 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1cae0 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  k X..**.** ^Only
1caf0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1cb00 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1cb10 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1cb20 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1cb30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cb40 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1cb50 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1cb60 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1cb70 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1cb80 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1cb90 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1cba0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1cbb0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1cbc0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1cbd0 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1cbe0 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1cbf0 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1cc00 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1cc10 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1cc20 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1cc30 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1cc40 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1cc50 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1cc60 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1cc70 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1cc80 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1cc90 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1cca0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1ccb0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1ccc0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1ccd0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1cce0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1ccf0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1cd00 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1cd10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1cd20 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1cd30 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1cd40 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1cd50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cd60 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1cd70 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1cd80 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1cd90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cda0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1cdb0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1cdc0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1cdd0 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
1cde0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1cdf0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1ce00 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
1ce10 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1ce20 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
1ce30 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
1ce40 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
1ce50 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1ce60 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1ce70 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1ce80 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
1ce90 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
1cea0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
1ceb0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1cec0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1ced0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1cee0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1cef0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1cf00 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1cf10 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1cf20 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1cf30 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1cf40 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
1cf50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1cf60 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
1cf70 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
1cf80 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
1cf90 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1cfa0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
1cfb0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
1cfc0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
1cfd0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1cfe0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1cff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1d000 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
1d010 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
1d020 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
1d030 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
1d040 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
1d050 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
1d060 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1d070 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
1d080 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
1d090 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
1d0a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1d0b0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
1d0c0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1d0d0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1d0e0 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
1d0f0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1d100 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1d110 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1d120 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1d130 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1d140 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1d150 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1d160 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
1d170 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
1d180 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
1d190 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
1d1a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
1d1b0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
1d1c0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
1d1d0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
1d1e0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
1d1f0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1d200 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
1d210 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
1d220 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1d230 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
1d240 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
1d250 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
1d260 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
1d270 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
1d280 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
1d290 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
1d2a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1d2b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1d2c0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
1d2d0 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
1d2e0 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
1d2f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
1d300 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
1d310 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1d320 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1d330 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d340 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
1d350 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
1d360 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
1d370 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
1d380 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
1d390 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
1d3a0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
1d3b0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
1d3c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d3d0 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
1d3e0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
1d3f0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
1d400 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
1d410 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1d420 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1d430 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1d440 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1d450 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d460 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
1d470 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1d480 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1d490 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
1d4a0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1d4b0 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
1d4c0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1d4d0 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
1d4e0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
1d4f0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1d500 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
1d510 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1d520 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
1d530 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
1d540 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
1d550 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
1d560 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
1d570 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d580 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1d590 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1d5a0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
1d5b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1d5c0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1d5d0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1d5e0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
1d5f0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
1d600 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
1d610 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
1d620 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
1d630 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
1d640 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
1d650 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
1d660 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
1d670 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
1d680 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1d690 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1d6a0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1d6b0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1d6c0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1d6d0 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1d6e0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1d6f0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1d700 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1d710 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1d720 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
1d730 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
1d740 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
1d750 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
1d760 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
1d770 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1d780 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1d790 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
1d7a0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
1d7b0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
1d7c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1d7d0 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
1d7e0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
1d7f0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
1d800 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
1d810 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
1d820 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
1d830 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
1d840 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
1d850 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
1d860 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
1d870 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
1d880 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1d890 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1d8a0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1d8b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d8c0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1d8d0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1d8e0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1d8f0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1d900 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1d910 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1d920 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1d930 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1d940 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
1d950 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d960 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1d970 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1d980 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d990 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1d9a0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1d9b0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1d9c0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1d9d0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1d9e0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1d9f0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1da00 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1da10 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
1da20 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1da30 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1da40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1da50 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
1da60 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
1da70 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1da80 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
1da90 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1daa0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
1dab0 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
1dac0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1dad0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1dae0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
1daf0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1db00 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1db10 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1db20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
1db30 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
1db40 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
1db50 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
1db60 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
1db70 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
1db80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1db90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1dba0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1dbb0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
1dbc0 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
1dbd0 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
1dbe0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1dbf0 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
1dc00 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1dc10 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
1dc20 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
1dc30 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1dc40 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
1dc50 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
1dc60 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1dc70 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
1dc80 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
1dc90 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
1dca0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1dcb0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1dcc0 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
1dcd0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
1dce0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1dcf0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
1dd00 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1dd10 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1dd20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1dd30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1dd40 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1dd50 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1dd60 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1dd70 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1dd80 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1dd90 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1dda0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1ddb0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1ddc0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1ddd0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1dde0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1ddf0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1de00 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1de10 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1de20 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1de30 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1de40 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1de50 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1de60 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1de70 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1de80 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
1de90 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1dea0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1deb0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
1dec0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1ded0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
1dee0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
1def0 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
1df00 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
1df10 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
1df20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1df30 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
1df40 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
1df50 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
1df60 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
1df70 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
1df80 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
1df90 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
1dfa0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1dfb0 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
1dfc0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
1dfd0 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
1dfe0 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
1dff0 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
1e000 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
1e010 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
1e020 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1e030 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
1e040 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
1e050 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
1e060 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
1e070 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1e080 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
1e090 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
1e0a0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
1e0b0 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
1e0c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
1e0d0 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
1e0e0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1e0f0 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
1e100 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
1e110 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
1e120 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
1e130 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
1e140 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
1e150 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
1e160 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
1e170 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
1e180 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
1e190 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
1e1a0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
1e1b0 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
1e1c0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
1e1d0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
1e1e0 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
1e1f0 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
1e200 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1e210 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
1e220 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
1e230 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
1e240 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
1e250 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
1e260 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
1e270 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
1e280 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
1e290 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
1e2a0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
1e2b0 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
1e2c0 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
1e2d0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1e2e0 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
1e2f0 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
1e300 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
1e310 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
1e320 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
1e330 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
1e340 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
1e350 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
1e360 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
1e370 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
1e380 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
1e390 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
1e3a0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
1e3b0 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
1e3c0 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
1e3d0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
1e3e0 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
1e3f0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
1e400 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
1e410 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
1e420 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
1e430 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
1e440 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
1e450 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
1e460 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
1e470 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
1e480 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
1e490 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
1e4a0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
1e4b0 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f  ive path. .** ^O
1e4c0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
1e4d0 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
1e4e0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
1e4f0 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
1e500 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
1e510 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a  (e.g. "C:")..**.
1e520 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
1e530 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
1e540 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
1e550 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
1e560 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
1e570 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
1e580 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
1e590 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
1e5a0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
1e5b0 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
1e5c0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1e5d0 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  n]..** SQLite in
1e5e0 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c  terprets the fol
1e5f0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65  lowing three que
1e600 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
1e610 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
1e620 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
1e630 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
1e640 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
1e650 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
1e660 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
1e670 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
1e680 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
1e690 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1e6a0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
1e6b0 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
1e6c0 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
1e6d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1e6e0 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
1e6f0 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
1e700 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
1e710 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
1e720 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
1e730 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
1e740 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
1e750 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
1e760 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
1e770 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1e780 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
1e790 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
1e7a0 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
1e7b0 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
1e7c0 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
1e7d0 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
1e7e0 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
1e7f0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
1e800 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
1e810 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1e820 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1e830 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
1e840 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
1e850 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
1e860 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
1e870 72 20 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a  r "ro", "rw" or.
1e880 2a 2a 20 20 20 20 20 22 72 77 63 22 2e 20 41 74  **     "rwc". At
1e890 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
1e8a0 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
1e8b0 76 61 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f  value is an erro
1e8c0 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
1e8d0 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
1e8e0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
1e8f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1e900 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
1e910 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
1e920 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
1e930 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1e940 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
1e950 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
1e960 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
1e970 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70  ent to sqlite3_p
1e980 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66  repare_v2(). ^If
1e990 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
1e9a0 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
1e9b0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
1e9c0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1e9d0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
1e9e0 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
1e9f0 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
1ea00 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
1ea10 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1ea20 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
1ea30 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
1ea40 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
1ea50 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
1ea60 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1ea70 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
1ea80 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
1ea90 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
1eaa0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
1eab0 41 54 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ATE. ^If sqlite3
1eac0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a  _open_v2() is .*
1ead0 2a 20 20 20 20 20 75 73 65 64 2c 20 69 74 20 69  *     used, it i
1eae0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
1eaf0 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
1eb00 72 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  r the mode param
1eb10 65 74 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a  eter that is .**
1eb20 20 20 20 20 20 6c 65 73 73 20 72 65 73 74 72 69       less restri
1eb30 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
1eb40 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1eb50 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 61 73   flags passed as
1eb60 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20   the third .**  
1eb70 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a     parameter..**
1eb80 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
1eb90 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
1eba0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
1ebb0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
1ebc0 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
1ebd0 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
1ebe0 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
1ebf0 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
1ec00 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1ec10 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
1ec20 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1ec30 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
1ec40 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
1ec50 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
1ec60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ec70 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
1ec80 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
1ec90 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
1eca0 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
1ecb0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
1ecc0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
1ecd0 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
1ece0 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
1ecf0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1ed00 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
1ed10 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
1ed20 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
1ed30 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
1ed40 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
1ed50 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
1ed60 76 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20  viour requested 
1ed70 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
1ed80 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
1ed90 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
1eda0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1edb0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c  CACHE flag..** <
1edc0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
1edd0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
1ede0 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
1edf0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1ee00 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
1ee10 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
1ee20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1ee30 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1ee40 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
1ee50 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
1ee60 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
1ee70 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
1ee80 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
1ee90 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
1eea0 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
1eeb0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1eec0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
1eed0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1eee0 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
1eef0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
1ef00 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
1ef10 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
1ef20 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
1ef30 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
1ef40 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
1ef50 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
1ef60 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1ef70 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
1ef80 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1ef90 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
1efa0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
1efb0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
1efc0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
1efd0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
1efe0 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
1eff0 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
1f000 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
1f010 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
1f020 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
1f030 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
1f040 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
1f050 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
1f060 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
1f070 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
1f080 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1f090 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
1f0a0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
1f0b0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1f0c0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
1f0d0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
1f0e0 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
1f0f0 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
1f100 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
1f110 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
1f120 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1f130 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
1f140 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
1f150 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
1f160 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
1f170 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
1f180 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
1f190 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
1f1a0 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
1f1b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
1f1c0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1f1d0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
1f1e0 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
1f1f0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
1f200 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
1f210 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
1f220 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
1f230 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
1f240 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
1f250 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
1f260 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
1f270 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
1f280 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
1f290 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
1f2a0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1f2b0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1f2c0 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
1f2d0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
1f2e0 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
1f2f0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1f300 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
1f310 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
1f320 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
1f330 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
1f340 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
1f350 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1f360 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
1f370 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e  ta.db?vfs=unix-n
1f380 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20  olock <td>.**   
1f390 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
1f3a0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
1f3b0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
1f3c0 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
1f3d0 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72  -nolock"..** <tr
1f3e0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1f3f0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
1f400 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1f410 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
1f420 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
1f430 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
1f440 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
1f450 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
1f460 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
1f470 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1f480 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
1f490 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
1f4a0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
1f4b0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
1f4c0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
1f4d0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
1f4e0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
1f4f0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
1f500 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
1f510 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
1f520 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
1f530 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
1f540 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
1f550 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
1f560 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
1f570 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
1f580 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
1f590 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
1f5a0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
1f5b0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
1f5c0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
1f5d0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
1f5e0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
1f5f0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
1f600 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
1f610 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
1f620 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
1f630 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
1f640 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
1f650 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
1f660 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
1f670 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
1f680 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
1f690 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
1f6a0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
1f6b0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
1f6c0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1f6d0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
1f6e0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1f6f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f700 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
1f710 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
1f720 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
1f730 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
1f740 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
1f750 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
1f760 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
1f770 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
1f780 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
1f790 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
1f7a0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
1f7b0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1f7c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
1f7d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1f7e0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1f7f0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1f800 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1f810 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1f820 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1f830 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1f840 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1f850 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1f860 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1f870 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1f880 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1f890 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1f8a0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1f8b0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1f8c0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1f8d0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1f8e0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1f8f0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1f900 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1f910 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1f920 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1f930 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1f940 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1f950 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1f960 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1f970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1f980 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1f990 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1f9a0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1f9b0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1f9c0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1f9d0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
1f9e0 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
1f9f0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
1fa00 68 69 73 20 69 73 20 61 20 75 74 69 6c 69 74 79  his is a utility
1fa10 20 72 6f 75 74 69 6e 65 2c 20 75 73 65 66 75 6c   routine, useful
1fa20 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
1fa30 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
1fa40 65 63 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69  ecks.** to see i
1fa50 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
1fa60 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
1fa70 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
1fa80 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
1fa90 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
1faa0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
1fab0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 71 75   value of the qu
1fac0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
1fad0 2a 0a 2a 2a 20 54 68 65 20 7a 46 69 6c 65 6e 61  *.** The zFilena
1fae0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  me argument is t
1faf0 68 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  he filename poin
1fb00 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
1fb10 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d  the xOpen().** m
1fb20 65 74 68 6f 64 20 6f 66 20 61 20 56 46 53 20 69  ethod of a VFS i
1fb30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1fb40 54 68 65 20 7a 50 61 72 61 6d 20 61 72 67 75 6d  The zParam argum
1fb50 65 6e 74 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ent is the name 
1fb60 6f 66 20 74 68 65 0a 2a 2a 20 71 75 65 72 79 20  of the.** query 
1fb70 70 61 72 61 6d 65 74 65 72 20 77 65 20 73 65 65  parameter we see
1fb80 6b 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  k.  This routine
1fb90 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1fba0 75 65 20 6f 66 20 74 68 65 20 7a 50 61 72 61 6d  ue of the zParam
1fbb0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
1fbc0 20 69 74 20 65 78 69 73 74 73 2e 20 20 49 66 20   it exists.  If 
1fbd0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 64 6f  the parameter do
1fbe0 65 73 20 6e 6f 74 20 65 78 69 73 74 2c 20 74 68  es not exist, th
1fbf0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
1fc00 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1fc10 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  nter..**.** If t
1fc20 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67  he zFilename arg
1fc30 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75  ument to this fu
1fc40 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20  nction is not a 
1fc50 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
1fc60 69 74 65 0a 2a 2a 20 70 61 73 73 65 64 20 69 6e  ite.** passed in
1fc70 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 56 46 53  to the xOpen VFS
1fc80 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
1fc90 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
1fca0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73  is routine.** is
1fcb0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
1fcc0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
1fcd0 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ble..*/.const ch
1fce0 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
1fcf0 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
1fd00 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
1fd10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
1fd20 72 61 6d 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ram);.../*.** CA
1fd30 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
1fd40 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
1fd50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1fd60 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
1fd70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1fd80 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
1fd90 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
1fda0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1fdb0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
1fdc0 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
1fdd0 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
1fde0 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
1fdf0 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
1fe00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1fe10 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
1fe20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
1fe30 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
1fe40 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
1fe50 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
1fe60 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
1fe70 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1fe80 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
1fe90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
1fea0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
1feb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1fec0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
1fed0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
1fee0 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
1fef0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1ff00 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
1ff10 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1ff20 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
1ff30 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
1ff40 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
1ff50 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
1ff60 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
1ff70 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
1ff80 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
1ff90 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
1ffa0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
1ffb0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
1ffc0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
1ffd0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
1ffe0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
1fff0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
20000 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
20010 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
20020 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
20030 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
20040 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
20050 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
20060 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
20070 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
20080 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
20090 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
200a0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
200b0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
200c0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
200d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  .)^.**.** When t
200e0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
200f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
20100 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
20110 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
20120 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
20130 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
20140 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
20150 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
20160 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
20170 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
20180 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
20190 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
201a0 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
201b0 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
201c0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
201d0 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
201e0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
201f0 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
20200 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
20210 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
20220 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
20230 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
20240 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
20250 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
20260 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
20270 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
20280 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
20290 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
202a0 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
202b0 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
202c0 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
202d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
202e0 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
202f0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
20300 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
20310 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
20320 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
20330 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
20340 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
20350 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
20360 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
20370 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
20380 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
20390 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
203a0 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
203b0 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
203c0 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
203d0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
203e0 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
203f0 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
20400 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
20410 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
20420 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
20430 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
20440 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
20450 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
20460 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
20470 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
20480 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
20490 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
204a0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
204b0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
204c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
204d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
204e0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
204f0 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
20500 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
20510 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
20520 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
20530 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
20540 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
20550 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
20560 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
20570 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
20580 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
20590 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
205a0 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
205b0 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
205c0 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
205d0 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
205e0 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
205f0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
20600 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
20610 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
20620 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20630 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
20640 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
20650 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
20660 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
20670 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
20680 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
20690 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
206a0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
206b0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
206c0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
206d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
206e0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
206f0 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
20700 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
20710 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
20720 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
20730 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
20740 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
20750 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
20760 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
20770 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
20780 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
20790 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
207a0 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
207b0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
207c0 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
207d0 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
207e0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
207f0 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
20800 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
20810 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
20820 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
20830 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
20840 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
20850 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
20860 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
20870 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
20880 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
20890 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
208a0 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
208b0 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
208c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
208d0 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
208e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
208f0 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
20900 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
20910 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
20920 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
20930 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
20940 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
20950 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
20960 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
20970 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
20980 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
20990 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
209a0 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
209b0 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
209c0 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
209d0 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
209e0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
209f0 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
20a00 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
20a10 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
20a20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
20a30 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
20a40 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
20a50 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
20a60 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
20a70 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
20a80 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
20a90 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
20aa0 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
20ab0 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
20ac0 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
20ad0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
20ae0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
20af0 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
20b00 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
20b10 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
20b20 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
20b30 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
20b40 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
20b50 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
20b60 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
20b70 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
20b80 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
20b90 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
20ba0 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
20bb0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
20bc0 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
20bd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
20be0 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
20bf0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
20c00 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
20c10 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
20c20 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
20c30 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
20c40 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
20c50 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
20c60 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
20c70 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
20c80 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
20c90 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
20ca0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
20cb0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
20cc0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
20cd0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
20ce0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
20cf0 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
20d00 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
20d10 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
20d20 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
20d30 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
20d40 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
20d50 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
20d60 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
20d70 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
20d80 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
20d90 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
20da0 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
20db0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
20dc0 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
20dd0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
20de0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
20df0 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
20e00 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
20e10 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
20e20 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
20e30 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
20e40 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
20e50 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
20e60 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
20e70 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
20e80 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
20e90 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
20ea0 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
20eb0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
20ec0 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
20ed0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
20ee0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20ef0 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
20f00 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
20f10 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
20f20 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
20f30 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
20f40 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
20f50 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
20f60 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
20f70 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
20f80 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
20f90 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
20fa0 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
20fb0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
20fc0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
20fd0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
20fe0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
20ff0 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
21000 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
21010 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
21020 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
21030 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
21040 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
21050 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
21060 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
21070 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
21080 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
21090 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
210a0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
210b0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
210c0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
210d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
210e0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
210f0 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
21100 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
21110 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
21120 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
21130 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
21140 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
21150 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
21160 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
21170 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
21180 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
21190 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
211a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
211b0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
211c0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
211d0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
211e0 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
211f0 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
21200 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
21210 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
21220 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
21230 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
21240 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
21250 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
21260 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
21270 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
21280 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
21290 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
212a0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
212b0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
212c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
212d0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
212e0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
212f0 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
21300 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
21310 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
21320 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
21330 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
21340 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
21350 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
21360 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
21370 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
21380 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
21390 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
213a0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
213b0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
213c0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
213d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
213e0 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
213f0 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
21400 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
21410 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
21420 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
21430 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
21440 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
21450 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
21460 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21470 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
21480 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
21490 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
214a0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
214b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
214c0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
214d0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
214e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
214f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
21500 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
21510 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
21520 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
21530 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
21540 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
21550 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
21560 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
21570 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
21580 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
21590 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
215a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
215b0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
215c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
215d0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
215e0 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
215f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
21600 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
21610 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
21620 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
21630 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
21640 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
21650 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
21660 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
21670 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
21680 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
21690 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
216a0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
216b0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
216c0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
216d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
216e0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
216f0 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
21700 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
21710 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
21720 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
21730 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
21740 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
21750 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
21760 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
21770 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
21780 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
21790 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
217a0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
217b0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
217c0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
217d0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
217e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
217f0 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
21800 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
21810 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
21820 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
21830 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
21840 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
21850 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
21860 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
21870 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
21880 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
21890 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
218a0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
218b0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
218c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
218d0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
218e0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
218f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
21900 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
21910 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
21920 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
21930 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
21940 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
21950 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
21960 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
21970 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
21980 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
21990 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
219a0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
219b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
219c0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
219d0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
219e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
219f0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
21a00 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
21a10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
21a20 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
21a30 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
21a40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
21a50 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
21a60 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
21a70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
21a80 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
21a90 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
21aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
21ab0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
21ac0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
21ad0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21ae0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
21af0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
21b00 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
21b10 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
21b20 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
21b30 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
21b40 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
21b50 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
21b60 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
21b70 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
21b80 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
21b90 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
21ba0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
21bb0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
21bc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
21bd0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
21be0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
21bf0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
21c00 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
21c10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21c20 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
21c30 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
21c40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21c50 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
21c60 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
21c70 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
21c80 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
21c90 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
21ca0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
21cb0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
21cc0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
21cd0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
21ce0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
21cf0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
21d00 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
21d10 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
21d20 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
21d30 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
21d40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21d50 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
21d60 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
21d70 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
21d80 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
21d90 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
21da0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
21db0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
21dc0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
21dd0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
21de0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
21df0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
21e00 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
21e10 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
21e20 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
21e30 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
21e40 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
21e50 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
21e60 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
21e70 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
21e80 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
21e90 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
21ea0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
21eb0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
21ec0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
21ed0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
21ee0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
21ef0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
21f00 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
21f10 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
21f20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
21f30 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
21f40 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
21f50 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
21f60 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
21f70 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
21f80 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
21f90 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
21fa0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
21fb0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
21fc0 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
21fd0 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
21fe0 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
21ff0 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
22000 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
22010 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
22020 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
22030 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
22040 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
22050 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
22060 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
22070 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
22080 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
22090 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
220a0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
220b0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
220c0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
220d0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
220e0 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
220f0 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
22100 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
22110 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
22120 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
22130 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22140 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
22150 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
22160 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22170 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
22180 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
22190 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
221a0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
221b0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
221c0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
221d0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
221e0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
221f0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
22200 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
22210 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
22220 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
22230 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
22240 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
22250 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
22260 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
22270 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22280 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
22290 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
222a0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
222b0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
222c0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
222d0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
222e0 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
222f0 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
22300 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
22310 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
22320 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
22330 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
22340 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
22350 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
22360 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
22370 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
22380 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
22390 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
223a0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
223b0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
223c0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
223d0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
223e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
223f0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
22400 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
22410 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
22420 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
22430 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
22440 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
22450 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
22460 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
22470 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
22480 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
22490 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
224a0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
224b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
224c0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
224d0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
224e0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
224f0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
22500 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
22510 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
22520 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
22530 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
22540 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
22550 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
22560 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
22570 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
22580 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
22590 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
225a0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
225b0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
225c0 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
225d0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
225e0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
225f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22600 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
22610 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
22620 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
22630 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
22640 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
22650 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
22660 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
22670 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22680 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
22690 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
226a0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
226b0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
226c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
226d0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
226e0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
226f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
22700 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
22710 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
22720 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
22730 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
22740 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
22750 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
22760 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
22770 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
22780 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
22790 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
227a0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
227b0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
227c0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
227d0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
227e0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
227f0 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
22800 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
22810 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
22820 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
22830 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
22840 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
22850 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
22860 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
22870 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
22880 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
22890 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
228a0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
228b0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
228c0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
228d0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
228e0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
228f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
22900 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
22910 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
22920 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
22930 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
22940 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
22950 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
22960 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
22970 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
22980 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
22990 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
229a0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
229b0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
229c0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
229d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
229e0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
229f0 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
22a00 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
22a10 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
22a20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
22a30 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
22a40 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
22a50 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
22a60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
22a70 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
22a80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
22a90 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
22aa0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
22ab0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
22ac0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
22ad0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
22ae0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
22af0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
22b00 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
22b10 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
22b20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
22b30 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
22b40 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
22b50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
22b60 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
22b70 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
22b80 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
22b90 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
22ba0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
22bb0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
22bc0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
22bd0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
22be0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
22bf0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
22c00 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
22c10 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
22c20 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
22c30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
22c40 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
22c50 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
22c60 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
22c70 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
22c80 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
22c90 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
22ca0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
22cb0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
22cc0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
22cd0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
22ce0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
22cf0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
22d00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
22d10 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
22d20 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
22d30 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
22d40 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
22d50 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
22d60 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
22d70 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
22d80 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
22d90 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
22da0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
22db0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
22dc0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
22dd0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
22de0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
22df0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
22e00 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
22e10 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
22e20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
22e30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22e40 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
22e50 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
22e60 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
22e70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
22e80 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
22e90 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22ea0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
22eb0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
22ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
22ed0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
22ee0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
22ef0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
22f00 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
22f10 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
22f20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
22f30 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
22f40 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
22f50 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
22f60 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
22f70 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
22f80 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
22f90 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
22fa0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
22fb0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
22fc0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
22fd0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
22fe0 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
22ff0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
23000 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
23010 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
23020 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
23030 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
23040 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
23050 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23060 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
23070 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
23080 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
23090 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
230a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
230b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
230c0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
230d0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
230e0 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
230f0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
23100 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
23110 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
23120 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
23130 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
23140 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
23150 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23160 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
23170 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
23180 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
23190 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
231a0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
231b0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
231c0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
231d0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
231e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
231f0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
23200 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
23210 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
23220 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
23230 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
23240 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
23250 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
23260 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
23270 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
23280 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
23290 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
232a0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
232b0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
232c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
232d0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
232e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
232f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
23300 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
23310 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
23320 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
23330 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
23340 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
23350 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
23360 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
23370 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
23380 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
23390 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
233a0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
233b0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
233c0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
233d0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
233e0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
233f0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
23400 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
23410 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
23420 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
23430 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
23440 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
23450 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
23460 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
23470 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
23480 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
23490 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
234a0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
234b0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
234c0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
234d0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
234e0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
234f0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
23500 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
23510 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
23520 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
23530 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
23540 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
23550 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
23560 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
23570 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
23580 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
23590 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
235a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
235b0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
235c0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
235d0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
235e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
235f0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
23600 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
23610 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
23620 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
23630 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23640 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
23650 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23660 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
23670 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
23680 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
23690 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
236a0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
236b0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
236c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
236d0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
236e0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
236f0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
23700 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
23710 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
23720 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
23730 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
23740 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
23750 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
23760 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
23770 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
23780 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
23790 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
237a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
237b0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
237c0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
237d0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
237e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
237f0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
23800 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
23810 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
23820 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
23830 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
23840 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
23850 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
23860 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
23870 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
23880 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
23890 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
238a0 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
238b0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
238c0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
238d0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
238e0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
238f0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
23900 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
23910 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
23920 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
23930 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
23940 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
23950 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
23960 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
23970 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
23980 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
23990 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
239a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
239b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
239c0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
239d0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
239e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
239f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
23a00 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
23a10 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23a20 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
23a30 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
23a40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
23a50 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
23a60 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
23a70 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
23a80 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
23a90 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
23aa0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
23ab0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
23ac0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
23ad0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
23ae0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
23af0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
23b00 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
23b10 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
23b20 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
23b30 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
23b40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23b50 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
23b60 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
23b70 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
23b80 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
23b90 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
23ba0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23bb0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
23bc0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
23bd0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
23be0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
23bf0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
23c00 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
23c10 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
23c20 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
23c30 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
23c40 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
23c50 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
23c60 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
23c70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23c80 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
23c90 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
23ca0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
23cb0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
23cc0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
23cd0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
23ce0 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
23cf0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
23d00 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
23d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
23d20 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
23d30 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
23d40 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
23d50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
23d60 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
23d70 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
23d80 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
23d90 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
23da0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
23db0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
23dc0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
23dd0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
23de0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
23df0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
23e00 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
23e10 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
23e20 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
23e30 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
23e40 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
23e50 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
23e60 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
23e70 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
23e80 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
23e90 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
23ea0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
23eb0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
23ec0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
23ed0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
23ee0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
23ef0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
23f00 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
23f10 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
23f20 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
23f30 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
23f40 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
23f50 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
23f60 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
23f70 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
23f80 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
23f90 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
23fa0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
23fb0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
23fc0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
23fd0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
23fe0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
23ff0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
24000 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
24010 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
24020 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
24030 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
24040 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
24050 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
24060 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
24070 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
24080 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
24090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
240a0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
240b0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
240c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
240d0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
240e0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
240f0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
24100 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
24110 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
24120 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
24130 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
24140 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
24150 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
24160 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
24170 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
24180 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
24190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
241a0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
241b0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
241c0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
241d0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
241e0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
241f0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
24200 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
24210 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
24220 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
24230 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
24240 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
24250 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
24260 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
24270 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
24280 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
24290 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
242a0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
242b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
242c0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
242d0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
242e0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
242f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
24300 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
24310 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
24320 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
24330 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
24340 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
24350 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
24360 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
24370 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
24380 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
24390 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
243a0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
243b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
243c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
243d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
243e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
243f0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
24400 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
24410 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
24420 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
24430 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
24440 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
24450 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
24460 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
24470 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
24480 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
24490 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
244a0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
244b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
244c0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
244d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
244e0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
244f0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
24500 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
24510 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
24520 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
24530 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
24540 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
24550 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
24560 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
24570 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
24580 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
24590 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
245a0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
245b0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
245c0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
245d0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
245e0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
245f0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
24600 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
24610 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
24620 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
24630 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
24640 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
24650 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
24660 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
24670 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
24680 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
24690 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
246a0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
246b0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
246c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
246d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
246e0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
246f0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
24700 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
24710 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
24720 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
24730 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
24740 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
24750 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
24760 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
24770 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
24780 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
24790 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
247a0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
247b0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
247c0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
247d0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
247e0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
247f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
24800 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
24810 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
24820 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
24830 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
24840 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
24850 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
24860 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
24870 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
24880 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
24890 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
248a0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
248b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
248c0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
248d0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
248e0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
248f0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
24900 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
24910 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
24920 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
24930 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
24940 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
24950 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
24960 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
24970 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
24980 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
24990 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
249a0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
249b0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
249c0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
249d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
249e0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
249f0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
24a00 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
24a10 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
24a20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
24a30 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
24a40 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
24a50 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
24a60 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
24a70 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
24a80 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
24a90 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
24aa0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
24ab0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
24ac0 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
24ad0 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
24ae0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
24af0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
24b00 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
24b10 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
24b20 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e  nator..** If a n
24b30 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
24b40 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
24b50 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
24b60 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
24b70 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
24b80 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e  nd_text16() then
24b90 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
24ba0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
24bb0 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
24bc0 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
24bd0 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
24be0 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
24bf0 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
24c00 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
24c10 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
24c20 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
24c30 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
24c40 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
24c50 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
24c60 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
24c70 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
24c80 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
24c90 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
24ca0 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
24cb0 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
24cc0 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
24cd0 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
24ce0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
24cf0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
24d00 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
24d10 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
24d20 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
24d30 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
24d40 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
24d50 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
24d60 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
24d70 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
24d80 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
24d90 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
24da0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
24db0 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
24dc0 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
24dd0 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
24de0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
24df0 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
24e00 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
24e10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
24e20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
24e30 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
24e40 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
24e50 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
24e60 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
24e70 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
24e80 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
24e90 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
24ea0 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
24eb0 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
24ec0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
24ed0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
24ee0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
24ef0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
24f00 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
24f10 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
24f20 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
24f30 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
24f40 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
24f50 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
24f60 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
24f70 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
24f80 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
24f90 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
24fa0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
24fb0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
24fc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
24fd0 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
24fe0 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
24ff0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
25000 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
25010 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
25020 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
25030 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
25040 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
25050 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
25060 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
25070 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
25080 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
25090 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
250a0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
250b0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
250c0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
250d0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
250e0 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
250f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
25100 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
25110 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
25120 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
25130 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
25140 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
25150 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
25160 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
25170 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
25180 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
25190 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
251a0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
251b0 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
251c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
251d0 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
251e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
251f0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
25200 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25210 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
25220 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
25230 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
25240 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
25250 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
25260 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
25270 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
25280 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
25290 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
252a0 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
252b0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
252c0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
252d0 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
252e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
252f0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
25300 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
25310 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
25320 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
25330 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
25340 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
25350 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
25360 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25370 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
25380 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
25390 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
253a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
253b0 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
253c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
253d0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
253e0 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
253f0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
25400 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
25410 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
25420 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
25430 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
25440 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
25450 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
25460 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25470 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25480 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
25490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
254a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
254b0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
254c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
254d0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
254e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
254f0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
25500 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
25510 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
25520 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
25530 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
25540 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
25550 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
25560 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
25570 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
25580 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
25590 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
255a0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
255b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
255c0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
255d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
255e0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
255f0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
25600 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
25610 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
25620 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
25630 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
25640 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
25650 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
25660 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25670 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
25680 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
25690 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
256a0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
256b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
256c0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
256d0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
256e0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
256f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25700 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
25710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
25720 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
25730 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
25740 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
25750 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
25760 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
25770 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
25780 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
25790 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
257a0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
257b0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
257c0 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
257d0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
257e0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
257f0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
25800 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
25810 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
25820 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25830 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
25840 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
25850 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
25860 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
25870 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
25880 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
25890 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
258a0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
258b0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
258c0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
258d0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
258e0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
258f0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
25900 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
25910 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
25920 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
25930 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
25940 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
25950 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
25960 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25970 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25980 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
25990 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
259a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
259b0 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
259c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
259d0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
259e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
259f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
25a00 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
25a10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
25a20 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
25a30 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
25a40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
25a50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25a60 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
25a70 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
25a80 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
25a90 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
25aa0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
25ab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25ac0 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
25ad0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
25ae0 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
25af0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
25b00 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
25b10 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
25b20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
25b30 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
25b40 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
25b50 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
25b60 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
25b70 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
25b80 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
25b90 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
25ba0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
25bb0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
25bc0 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
25bd0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
25be0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
25bf0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
25c00 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
25c10 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
25c20 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
25c30 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
25c40 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
25c50 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
25c60 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
25c70 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
25c80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
25c90 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
25ca0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
25cb0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
25cc0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
25cd0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
25ce0 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
25cf0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
25d00 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
25d10 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
25d20 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
25d30 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
25d40 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
25d50 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
25d60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25d70 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
25d80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
25d90 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
25da0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
25db0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
25dc0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
25dd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25de0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
25df0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
25e00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
25e10 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
25e20 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25e30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
25e40 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
25e50 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
25e60 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
25e70 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
25e80 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
25e90 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
25ea0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
25eb0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
25ec0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
25ed0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
25ee0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
25ef0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
25f00 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
25f10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
25f20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
25f30 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
25f40 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
25f50 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
25f60 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
25f70 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
25f80 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
25f90 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
25fa0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
25fb0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
25fc0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
25fd0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
25fe0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
25ff0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26000 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
26010 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
26020 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
26030 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
26040 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
26050 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
26060 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
26070 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
26080 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
26090 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
260a0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
260b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
260c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
260d0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
260e0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
260f0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
26100 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
26110 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
26120 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
26130 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
26140 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
26150 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
26160 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
26170 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
26180 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
26190 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
261a0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
261b0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
261c0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
261d0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
261e0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
261f0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
26200 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
26210 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
26220 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
26230 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
26240 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
26250 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
26260 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
26270 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
26280 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26290 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
262a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
262b0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
262c0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
262d0 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
262e0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
262f0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
26300 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
26310 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
26320 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
26330 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
26340 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
26350 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
26360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
26370 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
26380 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
26390 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
263a0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
263b0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
263c0 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
263d0 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
263e0 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
263f0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
26400 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
26410 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
26420 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26430 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
26440 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
26450 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
26460 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
26470 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
26480 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
26490 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
264a0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
264b0 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
264c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
264d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
264e0 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
264f0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
26500 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
26510 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
26520 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
26530 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
26540 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
26550 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
26560 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
26570 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
26580 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
26590 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
265a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
265b0 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
265c0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
265d0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
265e0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
265f0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
26600 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
26610 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
26620 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26630 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
26640 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
26650 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
26660 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
26670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
26680 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
26690 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
266a0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
266b0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
266c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
266d0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
266e0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
266f0 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
26700 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
26710 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
26720 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
26730 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
26740 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
26750 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
26760 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
26770 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
26780 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
26790 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
267a0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
267b0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
267c0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
267d0 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
267e0 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
267f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
26800 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
26810 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
26820 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
26830 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
26840 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
26850 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
26860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
26870 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26880 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
26890 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
268a0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
268b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
268c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
268d0 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
268e0 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
268f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
26900 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
26910 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
26920 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
26930 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
26940 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
26950 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
26960 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
26970 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
26980 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
26990 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
269a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
269b0 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
269c0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
269d0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
269e0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
269f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
26a00 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
26a10 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
26a20 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
26a30 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
26a40 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
26a50 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
26a60 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
26a70 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
26a80 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
26a90 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
26aa0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
26ab0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
26ac0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26ad0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
26ae0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
26af0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
26b00 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
26b10 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
26b20 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
26b30 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
26b40 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
26b50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
26b60 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
26b70 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
26b80 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
26b90 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
26ba0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
26bb0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
26bc0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
26bd0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
26be0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
26bf0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
26c00 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
26c10 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
26c20 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
26c30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
26c40 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
26c50 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
26c60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
26c70 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
26c80 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
26c90 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
26ca0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
26cb0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
26cc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
26cd0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
26ce0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
26cf0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
26d00 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
26d10 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
26d20 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
26d30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
26d40 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
26d50 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
26d60 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
26d70 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
26d80 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
26d90 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
26da0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
26db0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
26dc0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
26dd0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
26de0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
26df0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
26e00 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
26e10 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
26e20 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
26e30 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
26e40 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
26e50 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
26e60 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
26e70 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
26e80 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
26e90 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
26ea0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
26eb0 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
26ec0 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
26ed0 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
26ee0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
26ef0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
26f00 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
26f10 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
26f20 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
26f30 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
26f40 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
26f50 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
26f60 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
26f70 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
26f80 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
26f90 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
26fa0 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
26fb0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
26fc0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
26fd0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
26fe0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
26ff0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
27000 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27010 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
27020 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
27030 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
27040 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
27050 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
27060 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
27070 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
27080 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
27090 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
270a0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
270b0 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
270c0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
270d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
270e0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
270f0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
27100 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
27110 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
27120 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
27130 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
27140 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
27150 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
27160 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
27170 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
27180 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
27190 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
271a0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
271b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
271c0 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
271d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
271e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
271f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
27200 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
27210 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
27220 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27230 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
27240 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
27250 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
27260 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
27270 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
27280 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
27290 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
272a0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
272b0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
272c0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
272d0 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
272e0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
272f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
27300 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
27310 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
27320 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
27330 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
27340 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
27350 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
27360 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
27370 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
27380 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
27390 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
273a0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
273b0 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
273c0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
273d0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
273e0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
273f0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
27400 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
27410 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
27420 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
27430 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
27440 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
27450 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
27460 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
27470 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
27480 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
27490 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
274a0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
274b0 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
274c0 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
274d0 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
274e0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
274f0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
27500 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
27510 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
27520 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
27530 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
27540 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
27550 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
27560 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
27570 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
27580 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
27590 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
275a0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
275b0 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
275c0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
275d0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
275e0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
275f0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
27600 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
27610 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
27620 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
27630 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
27640 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
27650 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
27660 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
27670 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
27680 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
27690 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
276a0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
276b0 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
276c0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
276d0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
276e0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
276f0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
27700 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
27710 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
27720 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
27730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
27740 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
27750 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
27760 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
27770 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
27780 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
27790 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
277a0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
277b0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
277c0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
277d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
277e0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
277f0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
27800 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
27810 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
27820 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27830 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
27840 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
27850 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
27860 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
27870 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
27880 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
27890 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
278a0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
278b0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
278c0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
278d0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
278e0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
278f0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
27900 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
27910 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
27920 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
27930 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
27940 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
27950 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
27960 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
27970 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27980 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
27990 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
279a0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
279b0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
279c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
279d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
279e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
279f0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
27a00 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
27a10 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
27a20 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
27a30 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
27a40 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
27a50 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
27a60 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
27a70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
27a80 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
27a90 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
27aa0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
27ab0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
27ac0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
27ad0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
27ae0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
27af0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
27b00 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
27b10 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
27b20 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
27b30 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
27b40 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
27b50 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
27b60 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
27b70 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
27b80 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
27b90 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
27ba0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
27bb0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
27bc0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
27bd0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
27be0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
27bf0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
27c00 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
27c10 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
27c20 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
27c30 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
27c40 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
27c50 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
27c60 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
27c70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
27c80 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
27c90 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
27ca0 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
27cb0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
27cc0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
27cd0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
27ce0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
27cf0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
27d00 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
27d10 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
27d20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
27d30 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
27d40 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
27d50 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
27d60 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
27d70 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
27d80 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
27d90 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
27da0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
27db0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
27dc0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
27dd0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
27de0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
27df0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
27e00 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
27e10 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
27e20 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
27e30 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
27e40 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
27e50 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
27e60 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
27e70 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
27e80 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
27e90 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
27ea0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
27eb0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
27ec0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
27ed0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
27ee0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
27ef0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
27f00 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
27f10 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
27f20 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
27f30 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
27f40 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
27f50 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
27f60 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
27f70 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
27f80 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
27f90 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
27fa0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
27fb0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
27fc0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
27fd0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
27fe0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
27ff0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
28000 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
28010 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
28020 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
28030 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
28040 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
28050 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
28060 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
28070 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
28080 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
28090 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
280a0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
280b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
280c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
280d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
280e0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
280f0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
28100 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
28110 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
28120 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
28130 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
28140 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
28150 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
28160 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
28170 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
28180 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
28190 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
281a0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
281b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
281c0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
281d0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
281e0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
281f0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
28200 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
28210 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
28220 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
28230 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
28240 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
28250 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
28260 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
28270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
28280 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
28290 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
282a0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
282b0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
282c0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
282d0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
282e0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
282f0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
28300 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
28310 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28320 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
28330 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
28340 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
28350 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
28360 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
28370 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
28380 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
28390 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
283a0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
283b0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
283c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
283d0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
283e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
283f0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
28400 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
28410 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
28420 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
28430 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
28440 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
28450 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
28460 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
28470 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
28480 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
28490 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
284a0 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
284b0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
284c0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
284d0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
284e0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
284f0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
28500 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
28510 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
28520 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
28530 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
28540 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
28550 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
28560 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
28570 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
28580 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
28590 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
285a0 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
285b0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
285c0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
285d0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
285e0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
285f0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
28600 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
28610 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
28620 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
28630 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
28640 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
28650 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
28660 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
28670 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
28680 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
28690 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
286a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
286b0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
286c0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
286d0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
286e0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
286f0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
28700 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
28710 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
28720 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
28730 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
28740 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
28750 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
28760 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
28770 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
28780 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
28790 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
287a0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
287b0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
287c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
287d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
287e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
287f0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
28800 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
28810 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
28820 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28830 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
28840 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
28850 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
28860 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
28870 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
28880 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
28890 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
288a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
288b0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
288c0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
288d0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
288e0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
288f0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
28900 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
28910 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
28920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
28930 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
28940 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
28950 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
28960 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
28970 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
28980 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
28990 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
289a0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
289b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
289c0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
289d0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
289e0 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
289f0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
28a00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
28a10 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
28a20 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
28a30 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
28a40 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
28a50 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
28a60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
28a70 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
28a80 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
28a90 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
28aa0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
28ab0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
28ac0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
28ad0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
28ae0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
28af0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
28b00 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
28b10 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
28b20 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
28b30 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
28b40 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
28b50 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
28b60 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28b70 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
28b80 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
28b90 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
28ba0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
28bb0 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
28bc0 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
28bd0 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
28be0 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
28bf0 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
28c00 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
28c10 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
28c20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
28c30 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
28c40 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
28c50 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
28c60 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
28c70 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
28c80 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
28c90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
28ca0 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
28cb0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
28cc0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
28cd0 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
28ce0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
28cf0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
28d00 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
28d10 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
28d20 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
28d30 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
28d40 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
28d50 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
28d60 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
28d70 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
28d80 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
28d90 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
28da0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
28db0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
28dc0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
28dd0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
28de0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
28df0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
28e00 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
28e10 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
28e20 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
28e30 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
28e40 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
28e50 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
28e60 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
28e70 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
28e80 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
28e90 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
28ea0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
28eb0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
28ec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
28ed0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
28ee0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
28ef0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
28f00 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
28f10 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
28f20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
28f30 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
28f40 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
28f50 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
28f60 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
28f70 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
28f80 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
28f90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28fa0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
28fb0 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
28fc0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
28fd0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
28fe0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
28ff0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
29000 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
29010 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
29020 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
29030 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
29040 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
29050 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
29060 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
29070 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
29080 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
29090 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
290a0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
290b0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
290c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
290d0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
290e0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
290f0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
29100 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
29110 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
29120 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
29130 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
29140 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
29150 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
29160 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
29170 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
29180 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
29190 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
291a0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
291b0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
291c0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
291d0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
291e0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
291f0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
29200 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
29210 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
29220 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
29230 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
29240 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
29250 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
29260 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
29270 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
29280 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
29290 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
292a0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
292b0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
292c0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
292d0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
292e0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
292f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
29300 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
29310 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
29320 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
29330 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
29340 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
29350 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
29360 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
29370 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
29380 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
29390 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
293a0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
293b0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
293c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
293d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
293e0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
293f0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
29400 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
29410 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
29420 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
29430 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
29440 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
29450 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
29460 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
29470 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
29480 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
29490 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
294a0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
294b0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
294c0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
294d0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
294e0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
294f0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
29500 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
29510 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
29520 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
29530 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
29540 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
29550 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
29560 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
29570 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
29580 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
29590 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
295a0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
295b0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
295c0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
295d0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
295e0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
295f0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
29600 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
29610 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
29620 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29630 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
29640 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
29650 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
29660 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
29670 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
29680 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
29690 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
296a0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
296b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
296c0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
296d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
296e0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
296f0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
29700 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
29710 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
29720 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
29730 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
29740 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
29750 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
29760 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
29770 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
29780 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
29790 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
297a0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
297b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
297c0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
297d0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
297e0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
297f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
29800 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
29810 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
29820 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
29830 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
29840 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
29850 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29860 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
29870 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
29880 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
29890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
298a0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
298b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
298c0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
298d0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
298e0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
298f0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
29900 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
29910 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
29920 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
29930 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
29940 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29950 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
29960 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
29970 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
29980 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
29990 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
299a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
299b0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
299c0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
299d0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
299e0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
299f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
29a00 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
29a10 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
29a20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
29a30 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
29a40 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
29a50 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
29a60 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
29a70 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
29a80 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
29a90 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
29aa0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
29ab0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
29ac0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
29ad0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
29ae0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
29af0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
29b00 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
29b10 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
29b20 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
29b30 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
29b40 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
29b50 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
29b60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
29b70 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
29b80 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
29b90 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
29ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29bb0 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
29bc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29bd0 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
29be0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
29bf0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
29c00 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
29c10 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
29c20 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
29c30 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
29c40 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
29c50 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
29c60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29c70 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
29c80 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
29c90 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
29ca0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
29cb0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
29cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
29cd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
29ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29cf0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
29d00 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
29d10 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
29d20 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
29d30 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
29d40 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
29d50 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
29d60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
29d70 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
29d80 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
29d90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
29da0 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
29db0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
29dc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
29dd0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
29de0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
29df0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
29e00 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
29e10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
29e20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
29e30 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
29e40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
29e50 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
29e60 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
29e70 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
29e80 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29e90 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
29ea0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
29eb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29ec0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
29ed0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
29ee0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
29ef0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
29f00 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
29f10 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
29f20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
29f30 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
29f40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
29f50 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
29f60 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
29f70 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
29f80 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
29f90 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
29fa0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
29fb0 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
29fc0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
29fd0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
29fe0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
29ff0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2a000 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2a010 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2a020 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2a030 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2a040 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2a050 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2a060 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2a070 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2a080 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2a090 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2a0a0 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2a0b0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2a0c0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2a0d0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2a0e0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2a0f0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2a100 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2a110 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2a120 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2a130 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2a140 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2a150 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2a160 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2a170 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2a180 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2a190 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2a1a0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2a1b0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2a1c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2a1d0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2a1e0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2a1f0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2a200 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2a210 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2a220 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2a230 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2a240 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2a250 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2a260 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2a270 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2a280 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2a290 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2a2a0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2a2b0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2a2c0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2a2d0 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2a2e0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2a2f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2a300 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2a310 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
2a320 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
2a330 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
2a340 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2a350 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2a360 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
2a370 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2a380 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2a390 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
2a3a0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2a3b0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2a3c0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
2a3d0 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2a3e0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2a3f0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2a400 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
2a410 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2a420 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2a430 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2a440 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2a450 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2a460 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2a470 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2a480 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2a490 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2a4a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2a4b0 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2a4c0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
2a4d0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2a4e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2a4f0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2a500 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2a510 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2a520 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2a530 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2a540 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2a550 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2a560 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2a570 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2a580 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2a590 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2a5a0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2a5b0 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2a5c0 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2a5d0 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2a5e0 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2a5f0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2a600 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2a610 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2a620 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2a630 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2a640 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2a650 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2a660 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2a670 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2a680 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2a690 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2a6a0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2a6b0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2a6c0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2a6d0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2a6e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2a6f0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2a700 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2a710 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2a720 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2a730 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2a740 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2a750 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2a760 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2a770 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2a780 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2a790 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2a7a0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2a7b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a7c0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2a7d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a7e0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2a7f0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2a800 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2a810 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2a820 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2a830 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2a840 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2a850 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2a860 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2a870 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2a880 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2a890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2a8a0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2a8b0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2a8c0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2a8d0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2a8e0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2a8f0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2a900 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2a910 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2a920 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2a930 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2a940 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2a950 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2a960 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2a970 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2a980 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2a990 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2a9a0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2a9b0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2a9c0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2a9d0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2a9e0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2a9f0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2aa00 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2aa10 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2aa20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2aa30 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2aa40 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2aa50 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2aa60 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2aa70 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2aa80 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2aa90 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2aaa0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2aab0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2aac0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2aad0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2aae0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2aaf0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2ab00 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2ab10 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2ab20 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2ab30 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2ab40 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2ab50 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2ab60 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2ab70 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2ab80 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2ab90 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2aba0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2abb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2abc0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2abd0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2abe0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2abf0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2ac00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ac10 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2ac20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ac30 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2ac40 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2ac50 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2ac60 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2ac70 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2ac80 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2ac90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2aca0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2acb0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2acc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2acd0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2ace0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2acf0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2ad00 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2ad10 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2ad20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ad30 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2ad40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2ad50 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2ad60 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2ad70 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2ad80 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2ad90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2ada0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2adb0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2adc0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2add0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ade0 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2adf0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2ae00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ae10 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2ae20 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ae30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2ae40 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2ae50 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2ae60 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2ae70 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2ae80 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2ae90 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2aea0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2aeb0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2aec0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2aed0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2aee0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2aef0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2af00 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2af10 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2af20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2af30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2af40 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2af50 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2af60 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
2af70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2af80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
2af90 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
2afa0 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
2afb0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2afc0 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
2afd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2afe0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2aff0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
2b000 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
2b010 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
2b020 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
2b030 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
2b040 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
2b050 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
2b060 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
2b070 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2b080 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
2b090 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
2b0a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2b0b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2b0c0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
2b0d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2b0e0 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
2b0f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2b100 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2b110 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2b120 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2b130 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2b140 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2b150 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2b160 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b170 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b180 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
2b190 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2b1a0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2b1b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2b1c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2b1d0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
2b1e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2b1f0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2b200 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b210 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2b220 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2b230 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
2b240 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2b250 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
2b260 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2b270 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2b280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b290 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2b2a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2b2b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2b2c0 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
2b2d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2b2e0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
2b2f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2b300 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2b310 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
2b320 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b330 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
2b340 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2b350 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
2b360 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b370 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2b380 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
2b390 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b3a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
2b3b0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2b3c0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
2b3d0 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
2b3e0 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
2b3f0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
2b400 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
2b410 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
2b420 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
2b430 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
2b440 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
2b450 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2b460 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2b470 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
2b480 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
2b490 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2b4a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
2b4b0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2b4c0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
2b4d0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2b4e0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
2b4f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2b500 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
2b510 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2b520 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
2b530 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
2b540 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b550 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
2b560 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
2b570 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
2b580 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
2b590 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
2b5a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b5b0 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
2b5c0 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
2b5d0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
2b5e0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2b5f0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
2b600 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
2b610 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
2b620 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
2b630 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
2b640 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
2b650 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2b660 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2b670 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2b680 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
2b690 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
2b6a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
2b6b0 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
2b6c0 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
2b6d0 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
2b6e0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
2b6f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2b700 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
2b710 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b720 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2b730 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
2b740 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
2b750 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2b760 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2b770 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
2b780 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
2b790 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
2b7a0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
2b7b0 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
2b7c0 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
2b7d0 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
2b7e0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
2b7f0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
2b800 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2b810 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2b820 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2b830 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2b840 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2b850 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
2b860 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
2b870 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
2b880 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2b890 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
2b8a0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
2b8b0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
2b8c0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
2b8d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
2b8e0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
2b8f0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
2b900 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
2b910 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2b920 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2b930 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
2b940 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
2b950 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
2b960 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2b970 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2b980 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
2b990 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2b9a0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2b9b0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
2b9c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b9d0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
2b9e0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
2b9f0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
2ba00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2ba10 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2ba20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2ba30 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2ba40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ba50 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2ba60 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2ba70 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
2ba80 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2ba90 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2baa0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2bab0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
2bac0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2bad0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2bae0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2baf0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2bb00 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2bb10 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2bb20 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2bb30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2bb40 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2bb50 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
2bb60 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2bb70 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
2bb80 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2bb90 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
2bba0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2bbb0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2bbc0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2bbd0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
2bbe0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2bbf0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2bc00 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2bc10 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2bc20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2bc30 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2bc40 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2bc50 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2bc60 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2bc70 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
2bc80 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
2bc90 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2bca0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
2bcb0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2bcc0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2bcd0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
2bce0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2bcf0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2bd00 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
2bd10 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
2bd20 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2bd30 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2bd40 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2bd50 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2bd60 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2bd70 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2bd80 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2bd90 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2bda0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2bdb0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2bdc0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2bdd0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
2bde0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
2bdf0 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
2be00 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
2be10 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
2be20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2be30 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
2be40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
2be50 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
2be60 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
2be70 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
2be80 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2be90 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
2bea0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2beb0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2bec0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2bed0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
2bee0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2bef0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
2bf00 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
2bf10 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
2bf20 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
2bf30 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
2bf40 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2bf50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
2bf60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2bf70 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2bf80 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
2bf90 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
2bfa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2bfb0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2bfc0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
2bfd0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2bfe0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2bff0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2c000 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2c010 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
2c020 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
2c030 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
2c040 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
2c050 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
2c060 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
2c070 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
2c080 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
2c090 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
2c0a0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2c0b0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
2c0c0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
2c0d0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
2c0e0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
2c0f0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
2c100 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
2c110 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
2c120 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
2c130 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
2c140 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2c150 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
2c160 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
2c170 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2c180 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
2c190 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2c1a0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2c1b0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
2c1c0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
2c1d0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
2c1e0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2c1f0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
2c200 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
2c210 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
2c220 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
2c230 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
2c240 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2c250 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2c260 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
2c270 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
2c280 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
2c290 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
2c2a0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
2c2b0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
2c2c0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2c2d0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
2c2e0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
2c2f0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
2c300 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
2c310 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
2c320 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
2c330 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
2c340 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
2c350 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20  ers.  Every SQL 
2c360 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2c370 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
2c380 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
2c390 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
2c3a0 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
2c3b0 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
2c3c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
2c3d0 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
2c3e0 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
2c3f0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
2c400 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
2c410 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
2c420 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2c430 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2c440 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2c450 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2c460 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2c470 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2c480 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2c490 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2c4a0 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2c4b0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
2c4c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2c4d0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2c4e0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2c4f0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2c500 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2c510 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2c520 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2c530 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2c540 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2c550 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2c560 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2c570 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2c580 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2c590 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2c5a0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2c5b0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2c5c0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2c5d0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
2c5e0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2c5f0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2c600 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2c610 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2c620 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2c630 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2c640 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2c650 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2c660 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
2c670 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
2c680 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
2c690 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
2c6a0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
2c6b0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
2c6c0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
2c6d0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
2c6e0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2c6f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2c700 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
2c710 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
2c720 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2c730 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2c740 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
2c750 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
2c760 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
2c770 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2c780 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
2c790 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
2c7a0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
2c7b0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2c7c0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2c7d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
2c7e0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
2c7f0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
2c800 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
2c810 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
2c820 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
2c830 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
2c840 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2c850 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
2c860 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
2c870 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
2c880 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
2c890 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
2c8a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2c8b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c8c0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
2c8d0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
2c8e0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
2c8f0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2c900 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2c910 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
2c920 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
2c930 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
2c940 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
2c950 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
2c960 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
2c970 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2c980 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
2c990 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
2c9a0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
2c9b0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
2c9c0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2c9d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c9e0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
2c9f0 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
2ca00 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2ca10 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
2ca20 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
2ca30 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
2ca40 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
2ca50 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
2ca60 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
2ca70 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
2ca80 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
2ca90 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
2caa0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2cab0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2cac0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
2cad0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
2cae0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
2caf0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2cb00 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
2cb10 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
2cb20 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
2cb30 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
2cb40 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
2cb50 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
2cb60 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
2cb70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2cb80 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
2cb90 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
2cba0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2cbb0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
2cbc0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
2cbd0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
2cbe0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2cbf0 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
2cc00 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2cc10 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
2cc20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
2cc30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2cc40 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
2cc50 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
2cc60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
2cc70 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
2cc80 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
2cc90 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
2cca0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2ccb0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
2ccc0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
2ccd0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
2cce0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
2ccf0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2cd00 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
2cd10 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
2cd20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2cd30 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2cd40 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
2cd50 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
2cd60 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
2cd70 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
2cd80 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2cd90 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2cda0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
2cdb0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
2cdc0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
2cdd0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
2cde0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
2cdf0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
2ce00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2ce10 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
2ce20 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
2ce30 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2ce40 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
2ce50 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
2ce60 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
2ce70 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
2ce80 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
2ce90 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
2cea0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ceb0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
2cec0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
2ced0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2cee0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
2cef0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2cf00 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
2cf10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2cf20 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2cf30 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2cf40 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2cf50 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2cf60 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2cf70 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2cf80 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2cf90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2cfa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2cfb0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2cfc0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2cfd0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2cfe0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2cff0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2d000 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
2d010 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2d020 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
2d030 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2d040 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
2d050 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2d060 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2d070 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2d080 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2d090 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2d0a0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2d0b0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2d0c0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2d0d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2d0e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2d0f0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2d100 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2d110 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
2d120 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d130 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
2d140 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2d150 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2d160 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2d170 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2d180 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2d190 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2d1a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2d1b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2d1c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2d1d0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2d1e0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2d1f0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2d200 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2d210 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
2d220 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2d230 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
2d240 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
2d250 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
2d260 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2d270 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
2d280 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
2d290 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
2d2a0 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
2d2b0 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
2d2c0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
2d2d0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
2d2e0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2d2f0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
2d300 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
2d310 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
2d320 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
2d330 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
2d340 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
2d350 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
2d360 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
2d370 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
2d380 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
2d390 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d3a0 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
2d3b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2d3c0 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
2d3d0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2d3e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
2d3f0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
2d400 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
2d410 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
2d420 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
2d430 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2d440 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
2d450 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
2d460 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
2d470 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
2d480 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
2d490 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
2d4a0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
2d4b0 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
2d4c0 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
2d4d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
2d4e0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
2d4f0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
2d500 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
2d510 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
2d520 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
2d530 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
2d540 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
2d550 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
2d560 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
2d570 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
2d580 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
2d590 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
2d5a0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2d5b0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
2d5c0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2d5d0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2d5e0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2d5f0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2d600 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2d610 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2d620 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
2d630 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2d640 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
2d650 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2d660 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2d670 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
2d680 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
2d690 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2d6a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
2d6b0 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
2d6c0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2d6d0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2d6e0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
2d6f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2d700 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
2d710 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
2d720 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
2d730 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
2d740 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
2d750 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
2d760 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
2d770 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
2d780 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
2d790 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2d7a0 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
2d7b0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
2d7c0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
2d7d0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
2d7e0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
2d7f0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
2d800 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
2d810 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
2d820 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
2d830 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
2d840 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
2d850 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
2d860 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2d870 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2d880 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2d890 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2d8a0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
2d8b0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
2d8c0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2d8d0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2d8e0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
2d8f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2d900 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
2d910 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
2d920 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
2d930 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d940 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
2d950 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
2d960 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d970 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
2d980 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2d990 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
2d9a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2d9b0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
2d9c0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
2d9d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2d9e0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
2d9f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2da00 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
2da10 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
2da20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2da30 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
2da40 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
2da50 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
2da60 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2da70 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
2da80 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
2da90 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
2daa0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
2dab0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2dac0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
2dad0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
2dae0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2daf0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
2db00 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
2db10 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
2db20 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
2db30 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2db40 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
2db50 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
2db60 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
2db70 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
2db80 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
2db90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2dba0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2dbb0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
2dbc0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
2dbd0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
2dbe0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
2dbf0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
2dc00 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
2dc10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2dc20 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
2dc30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2dc40 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
2dc50 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
2dc60 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
2dc70 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
2dc80 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
2dc90 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
2dca0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
2dcb0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2dcc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
2dcd0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
2dce0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
2dcf0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
2dd00 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
2dd10 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
2dd20 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
2dd30 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
2dd40 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
2dd50 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
2dd60 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
2dd70 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
2dd80 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
2dd90 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
2dda0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
2ddb0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
2ddc0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
2ddd0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
2dde0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
2ddf0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
2de00 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
2de10 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
2de20 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
2de30 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
2de40 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
2de50 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
2de60 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
2de70 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
2de80 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
2de90 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
2dea0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
2deb0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
2dec0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
2ded0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
2dee0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2def0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2df00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2df10 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
2df20 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
2df30 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
2df40 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2df50 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
2df60 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2df70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2df80 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2df90 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2dfa0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
2dfb0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2dfc0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2dfd0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2dfe0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
2dff0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
2e000 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
2e010 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
2e020 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
2e030 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e040 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
2e050 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2e060 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2e070 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
2e080 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2e090 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2e0a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e0b0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
2e0c0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
2e0d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2e0e0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2e0f0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
2e100 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
2e110 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
2e120 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
2e130 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
2e140 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
2e150 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e160 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e170 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2e180 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e190 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2e1a0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2e1b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e1c0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
2e1d0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2e1e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2e1f0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
2e200 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2e210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2e220 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2e230 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2e240 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2e250 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2e260 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2e270 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
2e280 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
2e290 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
2e2a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2e2b0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2e2c0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
2e2d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
2e2e0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
2e2f0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
2e300 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
2e310 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
2e320 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2e330 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2e340 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
2e350 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
2e360 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
2e370 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
2e380 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
2e390 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
2e3a0 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
2e3b0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
2e3c0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2e3d0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
2e3e0 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
2e3f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
2e400 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
2e410 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2e420 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
2e430 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2e440 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
2e450 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
2e460 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
2e470 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2e480 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
2e490 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
2e4a0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
2e4b0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
2e4c0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
2e4d0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
2e4e0 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
2e4f0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
2e500 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
2e510 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
2e520 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
2e530 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
2e540 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
2e550 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
2e560 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
2e570 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
2e580 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
2e590 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
2e5a0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
2e5b0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
2e5c0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
2e5d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2e5e0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
2e5f0 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
2e600 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
2e610 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
2e620 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e630 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2e640 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
2e650 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
2e660 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
2e670 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
2e680 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
2e690 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2e6a0 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
2e6b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
2e6c0 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
2e6d0 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
2e6e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2e6f0 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
2e700 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
2e710 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
2e720 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
2e730 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
2e740 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
2e750 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
2e760 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
2e770 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2e780 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
2e790 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2e7a0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
2e7b0 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
2e7c0 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
2e7d0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
2e7e0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2e7f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2e800 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
2e810 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
2e820 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2e830 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
2e840 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
2e850 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
2e860 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2e870 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2e880 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
2e890 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2e8a0 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
2e8b0 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
2e8c0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
2e8d0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
2e8e0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
2e8f0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
2e900 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
2e910 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
2e920 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
2e930 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2e940 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2e950 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2e960 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2e970 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
2e980 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2e990 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2e9a0 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
2e9b0 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
2e9c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2e9d0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
2e9e0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
2e9f0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
2ea00 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
2ea10 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2ea20 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2ea30 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2ea40 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2ea50 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2ea60 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2ea70 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2ea80 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2ea90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2eaa0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2eab0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2eac0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2ead0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2eae0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2eaf0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2eb00 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2eb10 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
2eb20 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2eb30 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2eb40 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2eb50 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
2eb60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2eb70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2eb80 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
2eb90 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2eba0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ebb0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2ebc0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
2ebd0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
2ebe0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
2ebf0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
2ec00 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
2ec10 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2ec20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2ec30 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2ec40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ec50 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
2ec60 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
2ec70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2ec80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
2ec90 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2eca0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2ecb0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
2ecc0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
2ecd0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2ece0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2ecf0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
2ed00 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
2ed10 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2ed20 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
2ed30 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2ed40 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
2ed50 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
2ed60 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
2ed70 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
2ed80 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
2ed90 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2eda0 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
2edb0 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
2edc0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
2edd0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
2ede0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
2edf0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
2ee00 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
2ee10 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
2ee20 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
2ee30 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
2ee40 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
2ee50 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
2ee60 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
2ee70 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
2ee80 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
2ee90 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
2eea0 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
2eeb0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
2eec0 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
2eed0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
2eee0 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
2eef0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
2ef00 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
2ef10 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
2ef20 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
2ef30 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
2ef40 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
2ef50 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2ef60 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
2ef70 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
2ef80 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2ef90 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
2efa0 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
2efb0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2efc0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2efd0 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
2efe0 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
2eff0 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
2f000 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
2f010 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
2f020 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
2f030 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
2f040 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
2f050 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2f060 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
2f070 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
2f080 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
2f090 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2f0a0 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
2f0b0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2f0c0 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
2f0d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f0e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
2f0f0 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
2f100 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
2f110 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
2f120 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
2f130 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
2f140 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
2f150 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
2f160 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
2f170 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
2f180 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
2f190 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
2f1a0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2f1b0 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
2f1c0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2f1d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2f1e0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2f1f0 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
2f200 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
2f210 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
2f220 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
2f230 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
2f240 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
2f250 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
2f260 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f270 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
2f280 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2f290 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
2f2a0 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
2f2b0 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
2f2c0 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
2f2d0 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
2f2e0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
2f2f0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
2f300 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
2f310 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
2f320 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
2f330 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2f340 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
2f350 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
2f360 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
2f370 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
2f380 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
2f390 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
2f3a0 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
2f3b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2f3c0 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
2f3d0 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
2f3e0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
2f3f0 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
2f400 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
2f410 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
2f420 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
2f430 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
2f440 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
2f450 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
2f460 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
2f470 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
2f480 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
2f490 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
2f4a0 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
2f4b0 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
2f4c0 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
2f4d0 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
2f4e0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
2f4f0 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
2f500 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
2f510 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
2f520 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
2f530 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
2f540 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
2f550 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
2f560 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2f570 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2f580 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2f590 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2f5a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2f5b0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2f5c0 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
2f5d0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
2f5e0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
2f5f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
2f600 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2f610 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2f620 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
2f630 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
2f640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2f650 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
2f660 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
2f670 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
2f680 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
2f690 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
2f6a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
2f6b0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
2f6c0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
2f6d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
2f6e0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2f6f0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2f700 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
2f710 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
2f720 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
2f730 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
2f740 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2f750 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
2f760 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
2f770 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
2f780 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
2f790 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
2f7a0 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
2f7b0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
2f7c0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2f7d0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
2f7e0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
2f7f0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
2f800 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
2f810 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
2f820 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
2f830 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
2f840 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
2f850 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2f860 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
2f870 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
2f880 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
2f890 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
2f8a0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
2f8b0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
2f8c0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
2f8d0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2f8e0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
2f8f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
2f900 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
2f910 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2f920 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
2f930 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2f940 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
2f950 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
2f960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f970 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
2f980 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
2f990 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
2f9a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2f9b0 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
2f9c0 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
2f9d0 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
2f9e0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
2f9f0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2fa00 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
2fa10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fa20 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
2fa30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fa40 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
2fa50 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2fa60 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
2fa70 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2fa80 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
2fa90 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
2faa0 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
2fab0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
2fac0 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
2fad0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
2fae0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
2faf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fb00 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
2fb10 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
2fb20 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
2fb30 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
2fb40 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
2fb50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fb60 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
2fb70 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2fb80 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
2fb90 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
2fba0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2fbb0 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
2fbc0 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
2fbd0 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
2fbe0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
2fbf0 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
2fc00 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
2fc10 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
2fc20 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
2fc30 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2fc40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2fc50 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
2fc60 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
2fc70 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
2fc80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fc90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2fca0 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
2fcb0 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
2fcc0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
2fcd0 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
2fce0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2fcf0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2fd00 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2fd10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
2fd20 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
2fd30 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2fd40 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
2fd50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2fd60 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2fd70 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2fd80 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
2fd90 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
2fda0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2fdb0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2fdc0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
2fdd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fde0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
2fdf0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
2fe00 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
2fe10 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
2fe20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
2fe30 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
2fe40 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
2fe50 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
2fe60 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
2fe70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2fe80 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
2fe90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2fea0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
2feb0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
2fec0 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
2fed0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
2fee0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
2fef0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2ff00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2ff10 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
2ff20 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
2ff30 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
2ff40 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
2ff50 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
2ff60 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
2ff70 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
2ff80 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2ff90 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2ffa0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2ffb0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2ffc0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2ffd0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
2ffe0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
2fff0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
30000 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
30010 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
30020 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
30030 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
30040 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
30050 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
30060 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
30070 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30080 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
30090 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
300a0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
300b0 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
300c0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
300d0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
300e0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
300f0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
30100 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30110 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
30120 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30130 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
30140 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
30150 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
30160 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
30170 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
30180 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
30190 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
301a0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
301b0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
301c0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
301d0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
301e0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
301f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30200 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
30210 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
30220 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
30230 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
30240 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
30250 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
30260 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
30270 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
30280 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
30290 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
302a0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
302b0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
302c0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
302d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
302e0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
302f0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
30300 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
30310 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30320 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
30330 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
30340 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
30350 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
30360 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
30370 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
30380 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
30390 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
303a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
303b0 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
303c0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
303d0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
303e0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
303f0 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
30400 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
30410 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
30420 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30430 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
30440 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
30450 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
30460 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30470 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
30480 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
30490 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
304a0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
304b0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
304c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
304d0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
304e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
304f0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
30500 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
30510 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30520 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
30530 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
30540 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
30550 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
30560 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
30570 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
30580 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
30590 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
305a0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
305b0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
305c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
305d0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
305e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
305f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
30600 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30610 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
30620 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30630 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
30640 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
30650 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
30660 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
30670 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
30680 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30690 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
306a0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
306b0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
306c0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
306d0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
306e0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
306f0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
30700 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
30710 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
30720 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
30730 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
30740 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
30750 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30760 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
30770 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
30780 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30790 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
307a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
307b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
307c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
307d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
307e0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
307f0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
30800 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
30810 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
30820 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
30830 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
30840 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
30850 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
30860 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
30870 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
30880 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
30890 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
308a0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
308b0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
308c0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
308d0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
308e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
308f0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
30900 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
30910 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
30920 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
30930 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
30940 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
30950 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
30960 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
30970 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
30980 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
30990 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
309a0 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
309b0 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
309c0 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
309d0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
309e0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
309f0 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
30a00 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
30a10 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
30a20 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
30a30 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
30a40 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
30a50 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
30a60 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
30a70 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
30a80 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
30a90 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
30aa0 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
30ab0 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
30ac0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
30ad0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
30ae0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
30af0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30b00 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
30b10 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
30b20 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
30b30 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
30b40 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
30b50 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
30b60 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
30b70 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
30b80 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
30b90 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
30ba0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
30bb0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
30bc0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
30bd0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
30be0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
30bf0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
30c00 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
30c10 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
30c20 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
30c30 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
30c40 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
30c50 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
30c60 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
30c70 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
30c80 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
30c90 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
30ca0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
30cb0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
30cc0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
30cd0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
30ce0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
30cf0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
30d00 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
30d10 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
30d20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
30d30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
30d40 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
30d50 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
30d60 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
30d70 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
30d80 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
30d90 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
30da0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
30db0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
30dc0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
30dd0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
30de0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
30df0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
30e00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30e10 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
30e20 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
30e30 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
30e40 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
30e50 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30e60 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
30e70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
30e80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30e90 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
30ea0 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
30eb0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
30ec0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
30ed0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
30ee0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
30ef0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
30f00 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
30f10 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
30f20 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
30f30 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
30f40 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
30f50 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
30f60 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
30f70 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
30f80 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
30f90 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
30fa0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30fb0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
30fc0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
30fd0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
30fe0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30ff0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
31000 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
31010 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
31020 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
31030 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
31040 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
31050 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
31060 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
31070 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
31080 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
31090 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
310a0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
310b0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
310c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
310d0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
310e0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
310f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
31100 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
31110 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
31120 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
31130 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
31140 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31150 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
31160 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
31170 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
31180 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
31190 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
311a0 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
311b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
311c0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
311d0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
311e0 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
311f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31200 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
31210 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
31220 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
31230 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31240 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
31250 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
31260 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31270 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
31280 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31290 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
312a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
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 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
312d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
312e0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
312f0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
31300 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
31310 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
31320 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
31330 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
31340 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
31350 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31360 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31370 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
31380 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
31390 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
313a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
313b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
313c0 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
313d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
313e0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
313f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
31400 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31410 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
31420 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
31430 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
31440 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
31450 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31460 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
31470 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31480 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
31490 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
314a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
314b0 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
314c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
314d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
314e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
314f0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
31500 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
31510 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
31520 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
31530 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
31540 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ences.**.** ^The
31550 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
31560 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
31570 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
31580 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
31590 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
315a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
315b0 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
315c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
315d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
315e0 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
315f0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
31600 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
31610 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31620 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
31630 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31640 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
31650 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
31660 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
31670 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
31680 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
31690 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
316a0 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
316b0 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
316c0 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
316d0 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
316e0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
316f0 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
31700 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
31710 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
31720 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
31730 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
31740 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
31750 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
31760 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
31770 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
31780 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
31790 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
317a0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
317b0 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
317c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
317d0 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
317e0 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
317f0 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
31800 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
31810 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
31820 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
31830 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
31840 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
31850 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
31860 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
31870 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
31880 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
31890 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
318a0 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
318b0 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
318c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
318d0 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
318e0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
318f0 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
31900 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
31910 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
31920 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
31930 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
31940 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
31950 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
31960 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
31970 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
31980 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
31990 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
319a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
319b0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
319c0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
319d0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
319e0 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
319f0 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
31a00 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
31a10 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
31a20 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
31a30 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
31a40 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
31a50 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
31a60 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
31a70 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
31a80 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
31a90 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
31aa0 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
31ab0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
31ac0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
31ad0 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
31ae0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
31af0 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
31b00 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
31b10 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
31b20 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
31b30 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
31b40 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
31b50 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
31b60 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
31b70 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
31b80 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
31b90 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
31ba0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
31bb0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
31bc0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
31bd0 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
31be0 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
31bf0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
31c00 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
31c10 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
31c20 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
31c30 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
31c40 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
31c50 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
31c60 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
31c70 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
31c80 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
31c90 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
31ca0 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
31cb0 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
31cc0 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
31cd0 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
31ce0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
31cf0 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
31d00 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
31d10 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
31d20 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
31d30 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
31d40 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
31d50 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
31d60 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
31d70 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
31d80 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
31d90 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
31da0 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
31db0 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
31dc0 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
31dd0 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
31de0 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
31df0 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
31e00 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
31e10 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
31e20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
31e30 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
31e40 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
31e50 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
31e60 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
31e70 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
31e80 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
31e90 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
31ea0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
31eb0 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
31ec0 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
31ed0 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
31ee0 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
31ef0 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
31f00 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
31f10 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
31f20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
31f30 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
31f40 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
31f50 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
31f60 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
31f70 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
31f80 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
31f90 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
31fa0 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
31fb0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
31fc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31fd0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31fe0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
31ff0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32000 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
32010 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
32020 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
32030 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
32040 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
32050 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
32060 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
32070 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
32080 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
32090 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
320a0 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
320b0 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
320c0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
320d0 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
320e0 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
320f0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
32100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32110 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
32120 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
32130 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
32140 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
32150 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
32160 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
32170 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
32180 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
32190 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
321a0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
321b0 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
321c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
321d0 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
321e0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
321f0 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  roy argument sho
32200 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68  uld .** check th
32210 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e  e return code an
32220 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  d dispose of the
32230 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
32240 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  a pointer.** the
32250 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74  mselves rather t
32260 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51  han expecting SQ
32270 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74  Lite to deal wit
32280 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a  h it for them..*
32290 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72  * This is differ
322a0 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f  ent from every o
322b0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
322c0 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f  rface.  The inco
322d0 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73  nsistency .** is
322e0 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74   unfortunate but
322f0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
32300 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
32310 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a  ing backwards .*
32320 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
32330 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
32340 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
32350 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
32360 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
32370 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
32380 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
32390 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
323a0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
323b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
323c0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
323d0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
323e0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
323f0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
32400 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
32410 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
32420 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
32430 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
32440 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
32450 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
32460 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
32470 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
32480 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
32490 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
324a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
324b0 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
324c0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
324d0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
324e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
324f0 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
32500 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
32510 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
32520 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
32530 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
32540 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
32550 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
32560 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
32570 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
32580 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
32590 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
325a0 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
325b0 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
325c0 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
325d0 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
325e0 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
325f0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
32600 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
32610 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
32620 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
32630 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
32640 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
32650 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
32660 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
32670 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
32680 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
32690 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
326a0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
326b0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
326c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
326d0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
326e0 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
326f0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
32700 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
32710 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
32720 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
32730 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
32740 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  8. ^If sqlite3_c
32750 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
32760 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
32770 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
32780 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
32790 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
327a0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
327b0 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ^A call to eithe
327c0 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
327d0 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67  ces the existing
327e0 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65   collation-neede
327f0 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  d callback..**.*
32800 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c  * ^(When the cal
32810 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
32820 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
32830 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
32840 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
32850 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
32860 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
32870 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
32880 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
32890 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
328a0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
328b0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
328c0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
328d0 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
328e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
328f0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
32900 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
32910 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
32920 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
32930 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
32940 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
32950 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
32960 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
32970 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
32980 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
32990 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
329a0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
329b0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
329c0 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  equence.)^.**.**
329d0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
329e0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
329f0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
32a00 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
32a10 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
32a20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
32a30 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
32a40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
32a50 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
32a60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32a70 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
32a80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
32a90 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
32aa0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
32ab0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
32ac0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
32ad0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
32ae0 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
32af0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
32b00 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
32b10 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
32b20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
32b30 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
32b40 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
32b50 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c  ).);..#ifdef SQL
32b60 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a  ITE_HAS_CODEC./*
32b70 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
32b80 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
32b90 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
32ba0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
32bb0 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
32bc0 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
32bd0 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
32be0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
32bf0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
32c00 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
32c10 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
32c20 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
32c30 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
32c40 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
32c50 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
32c60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
32c70 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
32c80 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
32c90 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
32ca0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
32cb0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
32cc0 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
32cd0 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
32ce0 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
32cf0 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
32d00 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
32d10 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
32d20 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
32d30 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
32d40 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
32d50 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
32d60 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
32d70 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
32d80 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
32d90 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
32da0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
32db0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
32dc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32dd0 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
32de0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
32df0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
32e00 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
32e10 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
32e20 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
32e30 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
32e40 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
32e50 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
32e60 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
32e70 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
32e80 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
32e90 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
32ea0 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
32eb0 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
32ec0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
32ed0 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e  ivate_see(.  con
32ee0 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
32ef0 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
32f00 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
32f10 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23   */.);.#endif..#
32f20 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41  ifdef SQLITE_ENA
32f30 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20  BLE_CEROD./*.** 
32f40 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
32f50 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
32f60 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e   CEROD database.
32f70 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
32f80 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
32f90 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e  the CEROD routin
32fa0 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
32fb0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
32fc0 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
32fd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
32fe0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
32ff0 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
33000 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
33010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33020 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
33030 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
33040 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
33050 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
33060 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
33070 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
33080 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
33090 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
330a0 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
330b0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
330c0 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
330d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
330e0 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
330f0 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
33100 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
33110 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
33120 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
33130 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
33140 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
33150 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
33160 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
33170 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
33180 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
33190 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
331a0 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
331b0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
331c0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
331d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
331e0 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
331f0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
33200 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
33210 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
33220 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
33230 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
33240 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
33250 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
33260 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
33270 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
33280 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
33290 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
332a0 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
332b0 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
332c0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
332d0 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
332e0 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
332f0 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
33300 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
33310 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20  agraphs..*/.int 
33320 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
33330 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
33340 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
33350 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
33360 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
33370 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
33380 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
33390 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
333a0 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
333b0 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
333c0 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
333d0 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
333e0 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
333f0 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
33400 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
33410 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
33420 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
33430 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
33440 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
33450 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
33460 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
33470 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
33480 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
33490 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
334a0 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
334b0 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
334c0 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
334d0 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
334e0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
334f0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
33500 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
33510 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
33520 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
33530 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
33540 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
33550 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
33560 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
33570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33580 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
33590 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
335a0 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
335b0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
335c0 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
335d0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
335e0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
335f0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
33600 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
33610 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
33620 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
33630 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
33640 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
33650 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
33660 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
33670 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
33680 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
33690 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
336a0 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
336b0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
336c0 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
336d0 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
336e0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
336f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
33700 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
33710 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
33720 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
33730 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
33740 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
33750 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
33760 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
33770 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
33780 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
33790 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
337a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
337b0 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
337c0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
337d0 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
337e0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
337f0 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
33800 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
33810 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
33820 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
33830 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
33840 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
33850 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
33860 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
33870 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
33880 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
33890 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
338a0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
338b0 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
338c0 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
338d0 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
338e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
338f0 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
33900 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
33910 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
33920 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57  mit Mode.** KEYW
33930 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
33940 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54  t mode}.**.** ^T
33950 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
33960 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
33970 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
33980 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
33990 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
339a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
339b0 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
339c0 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
339d0 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
339e0 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69  ely.  ^Autocommi
339f0 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
33a00 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74  default..** ^Aut
33a10 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
33a20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
33a30 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
33a40 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
33a50 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
33a60 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
33a70 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
33a80 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
33a90 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
33aa0 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
33ab0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
33ac0 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
33ad0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
33ae0 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
33af0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
33b00 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
33b10 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
33b20 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
33b30 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
33b40 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
33b50 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
33b60 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
33b70 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
33b80 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
33b90 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
33ba0 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
33bb0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
33bc0 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
33bd0 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
33be0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
33bf0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
33c00 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
33c10 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
33c20 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
33c30 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
33c40 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
33c50 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
33c60 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
33c70 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
33c80 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
33c90 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
33ca0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
33cb0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
33cc0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
33cd0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
33ce0 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
33cf0 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
33d00 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
33d10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
33d20 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
33d30 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
33d40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33d50 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
33d60 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
33d70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
33d80 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
33d90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33da0 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
33db0 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
33dc0 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
33dd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33de0 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
33df0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
33e00 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
33e10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33e20 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
33e30 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
33e40 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
33e50 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
33e60 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
33e70 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c  st place..*/.sql
33e80 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
33e90 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
33ea0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
33eb0 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20  API3REF: Return 
33ec0 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72  The Filename For
33ed0 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
33ee0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
33ef0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c  e sqlite3_db_fil
33f00 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72  ename(D,N) inter
33f10 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
33f20 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65  ointer to a file
33f30 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74  name.** associat
33f40 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65  ed with database
33f50 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e   N of connection
33f60 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64   D.  ^The main d
33f70 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
33f80 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61  has the name "ma
33f90 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69  in".  If there i
33fa0 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61  s no attached da
33fb0 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20  tabase N on the 
33fc0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
33fd0 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20  ection D, or if 
33fe0 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20  database N is a 
33ff0 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d  temporary or in-
34000 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c  memory database,
34010 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20   then.** a NULL 
34020 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
34030 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
34040 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65  filename returne
34050 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
34060 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74  on is the output
34070 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c   of the.** xFull
34080 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20  Pathname method 
34090 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e  of the [VFS].  ^
340a0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
340b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
340c0 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c  will be an absol
340d0 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76  ute pathname, ev
340e0 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61  en if the filena
340f0 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70  me used.** to op
34100 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
34110 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61  originally was a
34120 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65   URI or relative
34130 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f   pathname..*/.co
34140 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
34150 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71  3_db_filename(sq
34160 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74  lite3 *db, const
34170 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b   char *zDbName);
34180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34190 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
341a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
341b0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
341c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
341d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
341e0 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
341f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
34200 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
34210 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
34220 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34230 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
34240 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
34250 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
34260 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
34270 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
34280 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
34290 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
342a0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
342b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
342c0 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
342d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
342e0 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
342f0 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
34300 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
34310 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
34320 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
34330 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
34340 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
34350 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
34360 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
34370 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
34380 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
34390 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
343a0 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
343b0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
343c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
343d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
343e0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
343f0 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
34400 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
34410 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34420 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
34430 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
34440 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
34450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34460 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
34470 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
34480 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
34490 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
344a0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
344b0 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
344c0 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
344d0 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e  mmitted]..** ^An
344e0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
344f0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
34500 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
34510 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
34520 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
34530 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
34540 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
34550 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f   ^The sqlite3_ro
34560 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
34570 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
34580 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
34590 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
345a0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
345b0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
345c0 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c   [ROLLBACK | rol
345d0 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41  led back]..** ^A
345e0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
345f0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
34600 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f  ll to sqlite3_ro
34610 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a  llback_hook().**
34620 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
34630 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34640 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
34650 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72  .** ^The pArg ar
34660 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
34670 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
34680 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66  callback..** ^If
34690 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
346a0 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
346b0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
346c0 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65  non-zero,.** the
346d0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
346e0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
346f0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
34700 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
34710 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  mmit_hook(D,C,P)
34720 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c   and sqlite3_rol
34730 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50  lback_hook(D,C,P
34740 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  ) functions.** r
34750 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75  eturn the P argu
34760 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
34770 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74  evious call of t
34780 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
34790 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
347a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
347b0 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
347c0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
347d0 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20  t call for each 
347e0 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a  function on D..*
347f0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20  *.** The commit 
34800 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  and rollback hoo
34810 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20  k callbacks are 
34820 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a  not reentrant..*
34830 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  * The callback i
34840 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
34850 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
34860 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
34870 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
34880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
34890 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
348a0 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61  callback.  Any a
348b0 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
348c0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
348d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
348e0 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
348f0 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
34900 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
34910 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
34920 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
34930 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69  ggered the commi
34940 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  t.** or rollback
34950 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72   hook in the fir
34960 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74  st place..** Not
34970 65 20 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61  e that running a
34980 6e 79 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61  ny other SQL sta
34990 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69  tements, includi
349a0 6e 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ng SELECT statem
349b0 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65  ents,.** or mere
349c0 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ly calling [sqli
349d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
349e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
349f0 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69  tep()] will modi
34a00 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
34a10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
34a20 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
34a30 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
34a40 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
34a50 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
34a60 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
34a70 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
34a80 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
34a90 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
34aa0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
34ab0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
34ac0 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
34ad0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
34ae0 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
34af0 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
34b00 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
34b10 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
34b20 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
34b30 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
34b40 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
34b50 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
34b60 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
34b70 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
34b80 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
34b90 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
34ba0 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
34bb0 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
34bc0 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
34bd0 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
34be0 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
34bf0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
34c00 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
34c10 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
34c20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
34c30 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
34c40 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
34c50 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
34c60 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
34c70 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
34c80 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
34c90 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
34ca0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
34cb0 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
34cc0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
34cd0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
34ce0 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
34cf0 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
34d00 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
34d10 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
34d20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34d30 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
34d40 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
34d50 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
34d60 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
34d70 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
34d80 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
34d90 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
34da0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
34db0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
34dc0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
34dd0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
34de0 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
34df0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34e00 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
34e10 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
34e20 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
34e30 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
34e40 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
34e50 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
34e60 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
34e70 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
34e80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
34e90 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
34ea0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
34eb0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
34ec0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
34ed0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
34ee0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
34ef0 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
34f00 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
34f10 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
34f20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
34f30 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
34f40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34f50 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
34f60 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
34f70 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
34f80 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
34f90 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
34fa0 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
34fb0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
34fc0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
34fd0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
34fe0 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
34ff0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
35000 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
35010 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
35020 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
35030 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
35040 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
35050 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
35060 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
35070 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
35080 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
35090 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
350a0 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
350b0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
350c0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
350d0 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
350e0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
350f0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
35100 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
35110 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
35120 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
35130 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
35140 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
35150 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
35160 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
35170 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
35180 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
35190 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
351a0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
351b0 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
351c0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
351d0 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
351e0 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
351f0 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
35200 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
35210 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
35220 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
35230 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
35240 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
35250 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
35260 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
35270 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
35280 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
35290 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
352a0 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
352b0 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
352c0 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
352d0 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
352e0 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
352f0 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
35300 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
35310 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
35320 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
35330 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
35340 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
35350 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
35360 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
35370 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
35380 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
35390 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
353a0 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
353b0 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
353c0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
353d0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
353e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
353f0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
35400 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
35410 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
35420 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
35430 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
35440 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
35450 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
35460 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
35470 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
35480 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
35490 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
354a0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
354b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
354c0 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
354d0 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
354e0 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
354f0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
35500 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
35510 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
35520 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
35530 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
35540 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
35550 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
35560 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
35570 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
35580 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35590 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
355a0 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
355b0 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
355c0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
355d0 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
355e0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
355f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35600 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
35610 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
35620 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
35630 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
35640 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
35650 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
35660 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
35670 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
35680 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
35690 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
356a0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
356b0 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
356c0 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
356d0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
356e0 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
356f0 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
35700 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
35710 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
35720 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
35730 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
35740 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
35750 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
35760 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
35770 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
35780 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
35790 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
357a0 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
357b0 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
357c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
357d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
357e0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
357f0 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
35800 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
35810 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
35820 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
35830 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
35840 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
35850 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
35860 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
35870 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
35880 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
35890 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
358a0 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
358b0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
358c0 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
358d0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
358e0 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
358f0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
35900 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
35910 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
35920 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
35930 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
35940 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
35950 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
35960 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
35970 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
35980 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
35990 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
359a0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
359b0 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
359c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
359d0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
359e0 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
359f0 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
35a00 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
35a10 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
35a20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
35a30 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
35a40 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
35a50 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
35a60 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
35a70 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
35a80 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
35a90 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
35aa0 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
35ab0 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
35ac0 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
35ad0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
35ae0 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
35af0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
35b00 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
35b10 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
35b20 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
35b30 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
35b40 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
35b50 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
35b60 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
35b70 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
35b80 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
35b90 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
35ba0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
35bb0 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
35bc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
35bd0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
35be0 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
35bf0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35c00 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
35c10 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
35c20 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
35c30 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
35c40 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
35c50 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
35c60 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
35c70 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
35c80 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
35c90 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
35ca0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
35cb0 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
35cc0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
35cd0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
35ce0 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
35cf0 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
35d00 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
35d10 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
35d20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
35d30 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
35d40 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
35d50 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
35d60 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
35d70 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
35d80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35d90 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
35da0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f   routine is a no
35db0 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65  -op returning ze
35dc0 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ro.** if SQLite 
35dd0 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20  is not compiled 
35de0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  with [SQLITE_ENA
35df0 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
35e00 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  EMENT]..**.** Se
35e10 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
35e20 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  _db_release_memo
35e30 72 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ry()].*/.int sql
35e40 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
35e50 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
35e60 20 43 41 50 49 33 52 45 46 3a 20 46 72 65 65 20   CAPI3REF: Free 
35e70 4d 65 6d 6f 72 79 20 55 73 65 64 20 42 79 20 41  Memory Used By A
35e80 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
35e90 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
35ea0 73 71 6c 69 74 65 33 5f 64 62 5f 73 68 72 69 6e  sqlite3_db_shrin
35eb0 6b 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 61  k(D) interface a
35ec0 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20  ttempts to free 
35ed0 61 73 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20  as much heap.** 
35ee0 6d 65 6d 6f 72 79 20 61 73 20 70 6f 73 73 69 62  memory as possib
35ef0 6c 65 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  le from database
35f00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 55   connection D. U
35f10 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 5b 73 71  nlike the.** [sq
35f20 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
35f30 6d 6f 72 79 28 29 5d 20 69 6e 74 65 72 66 61 63  mory()] interfac
35f40 65 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  e, this interfac
35f50 65 20 69 73 20 65 66 66 65 63 74 20 65 76 65 6e  e is effect even
35f60 0a 2a 2a 20 77 68 65 6e 20 74 68 65 6e 20 5b 53  .** when then [S
35f70 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
35f80 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 20  ORY_MANAGEMENT] 
35f90 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
35fa0 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74 74 65  ion is.** omitte
35fb0 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
35fc0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  o: [sqlite3_rele
35fd0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f  ase_memory()].*/
35fe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
35ff0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73  release_memory(s
36000 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
36010 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
36020 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
36030 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  p Size.**.** ^Th
36040 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
36050 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e  eap_limit64() in
36060 74 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64  terface sets and
36070 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a  /or queries the.
36080 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e  ** soft limit on
36090 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
360a0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
360b0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
360c0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e   by SQLite..** ^
360d0 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74  SQLite strives t
360e0 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f  o keep heap memo
360f0 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62  ry utilization b
36100 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65  elow the soft he
36110 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72  ap.** limit by r
36120 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62  educing the numb
36130 65 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64  er of pages held
36140 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63   in the page cac
36150 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65  he.** as heap me
36160 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72  mory usages appr
36170 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74  oaches the limit
36180 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68  ..** ^The soft h
36190 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f  eap limit is "so
361a0 66 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e  ft" because even
361b0 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73   though SQLite s
361c0 74 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a  trives to stay.*
361d0 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69  * below the limi
361e0 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65  t, it will excee
361f0 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68  d the limit rath
36200 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65  er than generate
36210 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  .** an [SQLITE_N
36220 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e  OMEM] error.  In
36230 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
36240 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
36250 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72  t .** is advisor
36260 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
36270 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
36280 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66  from sqlite3_sof
36290 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
362a0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a   is the size of.
362b0 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ** the soft heap
362c0 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20   limit prior to 
362d0 74 68 65 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74  the call.  ^If t
362e0 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
362f0 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65   negative.** the
36300 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d  n no change is m
36310 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20  ade to the soft 
36320 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e  heap limit.  Hen
36330 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ce, the current.
36340 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  ** size of the s
36350 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
36360 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
36370 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   by invoking.** 
36380 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
36390 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68  p_limit64() with
363a0 20 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75   a negative argu
363b0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ment..**.** ^If 
363c0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69  the argument N i
363d0 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20  s zero then the 
363e0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
363f0 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
36400 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65  ** ^(The soft he
36410 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  ap limit is not 
36420 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20  enforced in the 
36430 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
36440 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65  tation.** if one
36450 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c   or more of foll
36460 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73  owing conditions
36470 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a   are true:.**.**
36480 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
36490 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
364a0 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f  t is set to zero
364b0 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79  ..** <li> Memory
364c0 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64   accounting is d
364d0 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
364e0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74  combination of t
364f0 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  he.**      [sqli
36500 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
36510 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
36520 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74  ATUS],...) start
36530 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64  -time option and
36540 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51  .**      the [SQ
36550 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
36560 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d  STATUS] compile-
36570 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
36580 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74  <li> An alternat
36590 69 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69  ive page cache i
365a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
365b0 20 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67   specified using
365c0 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
365d0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
365e0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
365f0 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20  ],...)..** <li> 
36600 54 68 65 20 70 61 67 65 20 63 61 63 68 65 20 61  The page cache a
36610 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74  llocates from it
36620 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f  s own memory poo
36630 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20  l supplied.**   
36640 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63     by [sqlite3_c
36650 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
36660 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
36670 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61  ,...) rather tha
36680 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74  n.**      from t
36690 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c  he heap..** </ul
366a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e  >)^.**.** Beginn
366b0 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20  ing with SQLite 
366c0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74  version 3.7.3, t
366d0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
366e0 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a  it is enforced.*
366f0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
36700 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
36710 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
36720 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
36730 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  ENT].** compile-
36740 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69  time option is i
36750 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53  nvoked.  With [S
36760 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
36770 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c  ORY_MANAGEMENT],
36780 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61  .** the soft hea
36790 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72  p limit is enfor
367a0 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d  ced on every mem
367b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20  ory allocation. 
367c0 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c   Without.** [SQL
367d0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
367e0 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74  Y_MANAGEMENT], t
367f0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
36800 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72  it is only enfor
36810 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f  ced.** when memo
36820 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20  ry is allocated 
36830 62 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68  by the page cach
36840 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67 67  e.  Testing sugg
36850 65 73 74 73 20 74 68 61 74 20 62 65 63 61 75 73  ests that becaus
36860 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61  e.** the page ca
36870 63 68 65 20 69 73 20 74 68 65 20 70 72 65 64 6f  che is the predo
36880 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73  minate memory us
36890 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f  er in SQLite, mo
368a0 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
368b0 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20  ns will achieve 
368c0 61 64 65 71 75 61 74 65 20 73 6f 66 74 20 68 65  adequate soft he
368d0 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65  ap limit enforce
368e0 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ment without.** 
368f0 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49  the use of [SQLI
36900 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
36910 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a  _MANAGEMENT]..**
36920 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74  .** The circumst
36930 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69 63  ances under whic
36940 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e  h SQLite will en
36950 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20 68  force the soft h
36960 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a  eap limit may.**
36970 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75   changes in futu
36980 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
36990 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  QLite..*/.sqlite
369a0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
369b0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
369c0 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  4(sqlite3_int64 
369d0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
369e0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
369f0 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20  Soft Heap Limit 
36a00 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50  Interface.** DEP
36a10 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
36a20 69 73 20 69 73 20 61 20 64 65 70 72 65 63 61 74  is is a deprecat
36a30 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
36a40 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  e [sqlite3_soft_
36a50 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
36a60 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  ** interface.  T
36a70 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70  his routine is p
36a80 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73 74  rovided for hist
36a90 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
36aa0 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41  lity.** only.  A
36ab0 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  ll new applicati
36ac0 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ons should use t
36ad0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
36ae0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
36af0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61  ()] interface ra
36b00 74 68 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f  ther than this o
36b10 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45  ne..*/.SQLITE_DE
36b20 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
36b30 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
36b40 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a  limit(int N);...
36b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36b60 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61  Extract Metadata
36b70 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20   About A Column 
36b80 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  Of A Table.**.**
36b90 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
36ba0 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20  eturns metadata 
36bb0 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63  about a specific
36bc0 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65   column of a spe
36bd0 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73  cific.** databas
36be0 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62  e table accessib
36bf0 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61  le using the [da
36c00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36c10 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73  n] handle.** pas
36c20 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
36c30 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
36c40 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  nt..**.** ^The c
36c50 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66  olumn is identif
36c60 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
36c70 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  d, third and fou
36c80 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
36c90 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69  o.** this functi
36ca0 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  on. ^The second 
36cb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74  parameter is eit
36cc0 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  her the name of 
36cd0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
36ce0 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74  (i.e. "main", "t
36cf0 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61  emp", or an atta
36d00 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
36d10 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
36d20 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
36d30 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74   or NULL. ^If it
36d40 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61   is NULL, then a
36d50 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ll attached data
36d60 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68  bases are search
36d70 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61  ed.** for the ta
36d80 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ble using the sa
36d90 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65  me algorithm use
36da0 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
36db0 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72  e engine to.** r
36dc0 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
36dd0 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
36de0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ces..**.** ^The 
36df0 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
36e00 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
36e10 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  his function are
36e20 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63   the table and c
36e30 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66  olumn.** name of
36e40 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
36e50 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  umn, respectivel
36e60 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68  y. Neither of th
36e70 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  ese parameters.*
36e80 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a  * may be NULL..*
36e90 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69  *.** ^Metadata i
36ea0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72  s returned by wr
36eb0 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d  iting to the mem
36ec0 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61  ory locations pa
36ed0 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a  ssed as the 5th.
36ee0 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  ** and subsequen
36ef0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
36f00 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  this function. ^
36f10 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67  Any of these arg
36f20 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a  uments may be.**
36f30 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
36f40 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
36f50 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
36f60 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d  f metadata is om
36f70 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  itted..**.** ^(<
36f80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
36f90 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
36fa0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61  >.** <tr><th> Pa
36fb0 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74  rameter <th> Out
36fc0 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  put<br>Type <th>
36fd0 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a    Description.**
36fe0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68  .** <tr><td> 5th
36ff0 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
37000 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65  * <td> Data type
37010 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68  .** <tr><td> 6th
37020 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
37030 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64  * <td> Name of d
37040 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
37050 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72   sequence.** <tr
37060 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69  ><td> 7th <td> i
37070 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20  nt         <td> 
37080 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68  True if column h
37090 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  as a NOT NULL co
370a0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e  nstraint.** <tr>
370b0 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e  <td> 8th <td> in
370c0 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
370d0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
370e0 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49   part of the PRI
370f0 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e  MARY KEY.** <tr>
37100 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e  <td> 9th <td> in
37110 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
37120 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
37130 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d   [AUTOINCREMENT]
37140 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
37150 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
37160 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
37170 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
37180 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
37190 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
371a0 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61  for the.** decla
371b0 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20  ration type and 
371c0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
371d0 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79  ce is valid only
371e0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
371f0 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53  ** call to any S
37200 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69  QLite API functi
37210 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
37220 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c  e specified tabl
37230 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20  e is actually a 
37240 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20  view, an [error 
37250 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
37260 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
37270 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d   specified colum
37280 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f  n is "rowid", "o
37290 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22  id" or "_rowid_"
372a0 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45   and an.** [INTE
372b0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
372c0 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e   column has been
372d0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
372e0 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  ared, then the o
372f0 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74  utput.** paramet
37300 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20  ers are set for 
37310 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64  the explicitly d
37320 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20  eclared column. 
37330 5e 28 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f  ^(If there is no
37340 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64  .** explicitly d
37350 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52  eclared [INTEGER
37360 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f   PRIMARY KEY] co
37370 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f  lumn, then the o
37380 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74  utput.** paramet
37390 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66  ers are set as f
373a0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ollows:.**.** <p
373b0 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20  re>.**     data 
373c0 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a  type: "INTEGER".
373d0 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e  **     collation
373e0 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41   sequence: "BINA
373f0 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e  RY".**     not n
37400 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72  ull: 0.**     pr
37410 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20  imary key: 1.** 
37420 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65      auto increme
37430 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29  nt: 0.** </pre>)
37440 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66  ^.**.** ^(This f
37450 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64  unction may load
37460 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68   one or more sch
37470 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61  emas from databa
37480 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a  se files. If an.
37490 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  ** error occurs 
374a0 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63  during this proc
374b0 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ess, or if the r
374c0 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f  equested table o
374d0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e  r column.** cann
374e0 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20  ot be found, an 
374f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
37500 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20  returned and an 
37510 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65  error message le
37520 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61  ft.** in the [da
37530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37540 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  n] (to be retrie
37550 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
37560 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a  3_errmsg()).)^.*
37570 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69  *.** ^This API i
37580 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
37590 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
375a0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
375b0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
375c0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
375d0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
375e0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
375f0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
37600 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c  qlite3_table_col
37610 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20  umn_metadata(.  
37620 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
37630 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
37640 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
37650 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
37660 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
37670 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61    /* Database na
37680 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20  me or NULL */.  
37690 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
376a0 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54  leName,     /* T
376b0 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  able name */.  c
376c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
376d0 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f  mnName,    /* Co
376e0 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  lumn name */.  c
376f0 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61  har const **pzDa
37700 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55  taType,    /* OU
37710 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64  TPUT: Declared d
37720 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68  ata type */.  ch
37730 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c  ar const **pzCol
37740 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54  lSeq,     /* OUT
37750 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73  PUT: Collation s
37760 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a  equence name */.
37770 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c    int *pNotNull,
37780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
37790 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
377a0 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
377b0 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20  aint exists */. 
377c0 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65   int *pPrimaryKe
377d0 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  y,           /* 
377e0 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
377f0 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50  column part of P
37800 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74  K */.  int *pAut
37810 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20  oinc            
37820 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
37830 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
37840 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a  auto-increment *
37850 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
37860 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78  3REF: Load An Ex
37870 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  tension.**.** ^T
37880 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f  his interface lo
37890 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78  ads an SQLite ex
378a0 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
378b0 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66  from the named f
378c0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ile..**.** ^The 
378d0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
378e0 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
378f0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c  ce attempts to l
37900 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65  oad an.** SQLite
37910 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
37920 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
37930 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a  the file zFile..
37940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79  **.** ^The entry
37950 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e   point is zProc.
37960 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62  .** ^zProc may b
37970 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61  e 0, in which ca
37980 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  se the name of t
37990 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a  he entry point.*
379a0 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73  * defaults to "s
379b0 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e  qlite3_extension
379c0 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20  _init"..** ^The 
379d0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
379e0 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
379f0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ce returns.** [S
37a00 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
37a10 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45  cess and [SQLITE
37a20 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74  _ERROR] if somet
37a30 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
37a40 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
37a50 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72   occurs and pzEr
37a60 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74  rMsg is not 0, t
37a70 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  hen the.** [sqli
37a80 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
37a90 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  on()] interface 
37aa0 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
37ab0 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d  .** fill *pzErrM
37ac0 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65  sg with error me
37ad0 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65  ssage text store
37ae0 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f  d in memory.** o
37af0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
37b00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
37b10 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
37b20 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ction.** should 
37b30 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79  free this memory
37b40 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
37b50 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
37b60 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
37b70 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65  oading must be e
37b80 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nabled using.** 
37b90 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
37ba0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
37bb0 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ] prior to calli
37bc0 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20  ng this API,.** 
37bd0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
37be0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  or will be retur
37bf0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ned..**.** See a
37c00 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78  lso the [load_ex
37c10 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75  tension() SQL fu
37c20 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20  nction]..*/.int 
37c30 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
37c40 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  ension(.  sqlite
37c50 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37c60 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65  /* Load the exte
37c70 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20  nsion into this 
37c80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37c90 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
37ca0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f  har *zFile,    /
37cb0 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68  * Name of the sh
37cc0 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e  ared library con
37cd0 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f  taining extensio
37ce0 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
37cf0 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20  r *zProc,    /* 
37d00 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65  Entry point.  De
37d10 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65  rived from zFile
37d20 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20   if 0 */.  char 
37d30 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20  **pzErrMsg      
37d40 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65   /* Put error me
37d50 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f  ssage here if no
37d60 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  t 0 */.);../*.**
37d70 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
37d80 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
37d90 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a  ension Loading.*
37da0 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20  *.** ^So as not 
37db0 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79  to open security
37dc0 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20   holes in older 
37dd0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
37de0 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61  t are.** unprepa
37df0 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68  red to deal with
37e00 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
37e10 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61  ng, and as a mea
37e20 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a  ns of disabling.
37e30 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** extension loa
37e40 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75  ding while evalu
37e50 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72  ating user-enter
37e60 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c  ed SQL, the foll
37e70 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20  owing API.** is 
37e80 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e  provided to turn
37e90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
37ea0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
37eb0 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64  mechanism on and
37ec0 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74   off..**.** ^Ext
37ed0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69  ension loading i
37ee0 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  s off by default
37ef0 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38  . See ticket #18
37f00 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65  63..** ^Call the
37f10 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
37f20 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
37f30 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e   routine with on
37f40 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72  off==1.** to tur
37f50 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  n extension load
37f60 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20  ing on and call 
37f70 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30  it with onoff==0
37f80 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62   to turn.** it b
37f90 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a  ack off again..*
37fa0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
37fb0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
37fc0 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
37fd0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
37fe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
37ff0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
38000 20 53 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b   Statically Link
38010 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a  ed Extensions.**
38020 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
38030 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ace causes the x
38040 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e  EntryPoint() fun
38050 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
38060 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ked for.** each 
38070 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
38080 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69  nnection] that i
38090 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
380a0 69 64 65 61 20 68 65 72 65 20 69 73 20 74 68 61  idea here is tha
380b0 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74  t.** xEntryPoint
380c0 28 29 20 69 73 20 74 68 65 20 65 6e 74 72 79 20  () is the entry 
380d0 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74  point for a stat
380e0 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51  ically linked SQ
380f0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a  Lite extension.*
38100 2a 20 74 68 61 74 20 69 73 20 74 6f 20 62 65 20  * that is to be 
38110 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f  automatically lo
38120 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65  aded into all ne
38130 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
38140 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ctions..**.** ^(
38150 45 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20  Even though the 
38160 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79  function prototy
38170 70 65 20 73 68 6f 77 73 20 74 68 61 74 20 78 45  pe shows that xE
38180 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65  ntryPoint() take
38190 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74  s.** no argument
381a0 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f  s and returns vo
381b0 69 64 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  id, SQLite invok
381c0 65 73 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  es xEntryPoint()
381d0 20 77 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61   with three.** a
381e0 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70  rguments and exp
381f0 65 63 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72  ects and integer
38200 20 72 65 73 75 6c 74 20 61 73 20 69 66 20 74 68   result as if th
38210 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74  e signature of t
38220 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e  he.** entry poin
38230 74 20 77 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f  t where as follo
38240 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
38250 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26  quote><pre>.** &
38260 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 6e 74 72  nbsp;  int xEntr
38270 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70  yPoint(.** &nbsp
38280 3b 20 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62  ;    sqlite3 *db
38290 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63  ,.** &nbsp;    c
382a0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 45 72  onst char **pzEr
382b0 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20  rMsg,.** &nbsp; 
382c0 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20     const struct 
382d0 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
382e0 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20  ines *pThunk.** 
382f0 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f  &nbsp;  );.** </
38300 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
38310 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  >)^.**.** If the
38320 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75   xEntryPoint rou
38330 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73 20  tine encounters 
38340 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 73 68 6f  an error, it sho
38350 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d  uld make *pzErrM
38360 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  sg.** point to a
38370 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
38380 72 6f 72 20 6d 65 73 73 61 67 65 20 28 6f 62 74  ror message (obt
38390 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
383a0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a  te3_mprintf()]).
383b0 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e  ** and return an
383c0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
383d0 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c  ror code].  ^SQL
383e0 69 74 65 20 65 6e 73 75 72 65 73 20 74 68 61 74  ite ensures that
383f0 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73   *pzErrMsg.** is
38400 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c   NULL before cal
38410 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 72 79 50  ling the xEntryP
38420 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74 65  oint().  ^SQLite
38430 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
38440 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
38450 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61 66   on *pzErrMsg af
38460 74 65 72 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  ter xEntryPoint(
38470 29 20 72 65 74 75 72 6e 73 2e 20 20 5e 49 66 20  ) returns.  ^If 
38480 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69  any.** xEntryPoi
38490 6e 74 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20  nt() returns an 
384a0 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69  error, the [sqli
384b0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
384c0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
384d0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
384e0 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20  open_v2()] call 
384f0 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68  that provoked th
38500 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  e xEntryPoint() 
38510 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  will fail..**.**
38520 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
38530 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
38540 28 58 29 20 77 69 74 68 20 61 6e 20 65 6e 74 72  (X) with an entr
38550 79 20 70 6f 69 6e 74 20 58 20 74 68 61 74 20 69  y point X that i
38560 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20  s already.** on 
38570 74 68 65 20 6c 69 73 74 20 6f 66 20 61 75 74 6f  the list of auto
38580 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
38590 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
385a0 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20  o-op. ^No entry 
385b0 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65  point.** will be
385c0 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61   called more tha
385d0 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  n once for each 
385e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
385f0 69 6f 6e 20 74 68 61 74 20 69 73 20 6f 70 65 6e  ion that is open
38600 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
38610 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  so: [sqlite3_res
38620 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
38630 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  n()]..*/.int sql
38640 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
38650 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72  ion(void (*xEntr
38660 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a  yPoint)(void));.
38670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38680 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63   Reset Automatic
38690 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
386a0 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  ng.**.** ^This i
386b0 6e 74 65 72 66 61 63 65 20 64 69 73 61 62 6c 65  nterface disable
386c0 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20  s all automatic 
386d0 65 78 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69  extensions previ
386e0 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  ously.** registe
386f0 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  red using [sqlit
38700 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
38710 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  n()]..*/.void sq
38720 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
38730 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
38740 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  ;../*.** The int
38750 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
38760 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
38770 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
38780 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
38790 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
387a0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
387b0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
387c0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
387d0 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
387e0 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
387f0 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
38800 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
38810 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
38820 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
38830 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
38840 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
38850 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
38860 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** in