/ Hex Artifact Content
Login

Artifact f414e44e9eb1d13804b9da0123ac082b0604bebf:


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 5a 45 52 4f 5f 44 41 4d 41 47 45 5d 20 6f  L_ZERO_DAMAGE] o
8f40: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8f50: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
8f60: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
8f70: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 73 65 74 74  zero-damage sett
8f80: 69 6e 67 2e 20 20 54 68 65 20 7a 65 72 6f 2d 64  ing.  The zero-d
8f90: 61 6d 61 67 65 20 73 65 74 74 69 6e 67 20 64 65  amage setting de
8fa0: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 20  termines.** the 
8fb0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 5a 45  [SQLITE_IOCAP_ZE
8fc0: 52 4f 5f 44 41 4d 41 47 45 5d 20 62 69 74 20 6f  RO_DAMAGE] bit o
8fd0: 66 20 74 68 65 20 78 44 65 76 69 63 65 43 68 61  f the xDeviceCha
8fe0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
8ff0: 68 6f 64 73 2e 0a 2a 2a 20 54 68 65 20 66 6f 75  hods..** The fou
9000: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9010: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9020: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
9030: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
9040: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
9050: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
9060: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
9070: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
9080: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9090: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
90a0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
90b0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
90c0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
90d0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
90e0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
90f0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
9100: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
9110: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
9120: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9130: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
9140: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
9150: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
9160: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
9170: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
9180: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
9190: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
91a0: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
91b0: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
91c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
91d0: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
91e0: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
91f0: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
9200: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
9210: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
9220: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
9230: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
9240: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61  SNAME] opcode ca
9250: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
9260: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
9270: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20  .** all [VFSes] 
9280: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b  in the VFS stack
9290: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65  .  The names are
92a0: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d   of all VFS shim
92b0: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e  s and the.** fin
92c0: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20  al bottom-level 
92d0: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20  VFS are written 
92e0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
92f0: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
9300: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
9310: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20   and the result 
9320: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  is stored in the
9330: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a   char* variable.
9340: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72  ** that the four
9350: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
9360: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9370: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20  ntrol()] points 
9380: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65  to..** The calle
9390: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  r is responsible
93a0: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65   for freeing the
93b0: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e   memory when don
93c0: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61  e.  As with.** a
93d0: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ll file-control 
93e0: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69  actions, there i
93f0: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
9400: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63  hat this will ac
9410: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79  tually.** do any
9420: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20  thing.  Callers 
9430: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a  should initializ
9440: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  e the char* vari
9450: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  able to a NULL.*
9460: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73  * pointer in cas
9470: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
9480: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  rol is not imple
9490: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69  mented.  This fi
94a0: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73  le-control.** is
94b0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69   intended for di
94c0: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c  agnostic use onl
94d0: 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  y..*/.#define SQ
94e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
94f0: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64  TATE        1.#d
9500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
9510: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
9520: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
9530: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
9540: 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64  XYFILE      3.#d
9550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
9560: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
9570: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
9580: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9590: 48 49 4e 54 20 20 20 20 20 20 20 20 35 0a 23 64  HINT        5.#d
95a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
95b0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
95c0: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
95d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
95e0: 50 4f 49 4e 54 45 52 20 20 20 20 20 37 0a 23 64  POINTER     7.#d
95f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9600: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
9610: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
9620: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9630: 5f 41 56 5f 52 45 54 52 59 20 20 20 39 0a 23 64  _AV_RETRY   9.#d
9640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9650: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
9660: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
9670: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
9680: 52 49 54 45 20 20 20 20 20 20 20 31 31 0a 23 64  RITE       11.#d
9690: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
96a0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
96b0: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
96c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 45 52 4f 5f  LITE_FCNTL_ZERO_
96d0: 44 41 4d 41 47 45 20 20 20 20 20 31 33 0a 0a 2f  DAMAGE     13../
96e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
96f0: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
9700: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
9710: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
9720: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
9730: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
9740: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
9750: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
9760: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
9770: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
9780: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
9790: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
97a0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
97b0: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
97c0: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
97d0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
97e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
97f0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
9800: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
9810: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
9820: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
9830: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
9840: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
9850: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
9860: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
9870: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
9880: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
9890: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
98a0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
98b0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
98c0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
98d0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
98e0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
98f0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
9900: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
9910: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
9920: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
9930: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
9940: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
9950: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
9960: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
9970: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
9980: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
9990: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
99a0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
99b0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
99c0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
99d0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
99e0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
99f0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
9a00: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
9a10: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
9a20: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
9a30: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
9a40: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
9a50: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
9a60: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
9a70: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
9a80: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
9a90: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
9aa0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
9ab0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
9ac0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
9ad0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
9ae0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
9af0: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
9b00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
9b10: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
9b20: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
9b30: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
9b40: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
9b50: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
9b60: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
9b70: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
9b80: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
9b90: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
9ba0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
9bb0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
9bc0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
9bd0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
9be0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
9bf0: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
9c00: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
9c10: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
9c20: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
9c30: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
9c40: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
9c50: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
9c60: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
9c70: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
9c80: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
9c90: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
9ca0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
9cb0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
9cc0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
9cd0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
9ce0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9cf0: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
9d00: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
9d10: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
9d20: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
9d30: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
9d40: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
9d50: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
9d60: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
9d70: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
9d80: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
9d90: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
9da0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
9db0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
9dc0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
9dd0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
9de0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
9df0: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
9e00: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
9e10: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
9e20: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
9e30: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
9e40: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
9e50: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
9e60: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
9e70: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
9e80: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
9e90: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
9ea0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
9eb0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
9ec0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
9ed0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
9ee0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
9ef0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
9f00: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
9f10: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
9f20: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
9f30: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
9f40: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
9f50: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
9f60: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
9f70: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
9f80: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
9f90: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
9fa0: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
9fb0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
9fc0: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
9fd0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
9fe0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20  more than.** 10 
9ff0: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
a000: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
a010: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
a020: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
a030: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
a040: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
a050: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
a060: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
a070: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
a080: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
a090: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
a0a0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
a0b0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
a0c0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
a0d0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
a0e0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
a0f0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
a100: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
a110: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
a120: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
a130: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
a140: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
a150: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
a160: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
a170: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
a180: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
a190: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
a1a0: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
a1b0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
a1c0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
a1d0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
a1e0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
a1f0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
a200: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
a210: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
a220: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
a230: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
a240: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
a250: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
a260: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
a270: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
a280: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
a290: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
a2a0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
a2b0: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
a2c0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
a2d0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
a2e0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
a2f0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
a300: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
a310: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
a320: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
a330: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
a340: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
a350: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
a360: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
a370: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
a380: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
a390: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
a3a0: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
a3b0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
a3c0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
a3d0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
a3e0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
a3f0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
a400: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
a410: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
a420: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
a430: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
a440: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
a450: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
a460: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
a470: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
a480: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
a490: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
a4a0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
a4b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
a4c0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
a4d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
a4e0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
a4f0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
a500: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
a510: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
a520: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
a530: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
a540: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
a550: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
a560: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
a570: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
a580: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
a590: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
a5a0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
a5b0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
a5c0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
a5d0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
a5e0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
a5f0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
a600: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
a610: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
a620: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
a630: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
a640: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
a650: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
a660: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
a670: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
a680: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
a690: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
a6a0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
a6b0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
a6c0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
a6d0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
a6e0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
a6f0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
a700: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
a710: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
a720: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
a730: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
a740: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
a750: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
a760: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
a770: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
a780: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
a790: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
a7a0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
a7b0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
a7c0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
a7d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
a7e0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
a7f0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
a800: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
a810: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
a820: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
a830: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
a840: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
a850: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
a860: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
a870: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
a880: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
a890: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
a8a0: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
a8b0: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
a8c0: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
a8d0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
a8e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
a8f0: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
a900: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
a910: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
a920: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
a930: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
a940: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
a950: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
a960: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
a970: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
a980: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
a990: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
a9a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
a9b0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
a9c0: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
a9d0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
a9e0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
a9f0: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
aa00: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
aa10: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
aa20: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
aa30: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
aa40: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
aa50: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
aa60: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
aa70: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
aa80: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
aa90: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
aaa0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
aab0: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
aac0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
aad0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
aae0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
aaf0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
ab00: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
ab10: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
ab20: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
ab30: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
ab40: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
ab50: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
ab60: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
ab70: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
ab80: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
ab90: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
aba0: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
abb0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
abc0: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
abd0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
abe0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
abf0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
ac00: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
ac10: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
ac20: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
ac30: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
ac40: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
ac50: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
ac60: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
ac70: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
ac80: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
ac90: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
aca0: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
acb0: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
acc0: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
acd0: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
ace0: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
acf0: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
ad00: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
ad10: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
ad20: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
ad30: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
ad40: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
ad50: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
ad60: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
ad70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ad80: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
ad90: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
ada0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
adb0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
adc0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
add0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
ade0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
adf0: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
ae00: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
ae10: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
ae20: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
ae30: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
ae40: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
ae50: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
ae60: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
ae70: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
ae80: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
ae90: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
aea0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
aeb0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
aec0: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
aed0: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
aee0: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
aef0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
af00: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
af10: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
af20: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
af30: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
af40: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
af50: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
af60: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
af70: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
af80: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
af90: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
afa0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
afb0: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
afc0: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
afd0: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
afe0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
aff0: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
b000: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
b010: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
b020: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
b030: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
b040: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
b050: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
b060: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
b070: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
b080: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
b090: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
b0a0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
b0b0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
b0c0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
b0d0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
b0e0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
b0f0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
b100: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
b110: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
b120: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
b130: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
b140: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
b150: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
b160: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
b170: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
b180: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
b190: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
b1a0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
b1b0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
b1c0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
b1d0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
b1e0: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
b1f0: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
b200: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
b210: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
b220: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
b230: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
b240: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
b250: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
b260: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
b270: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
b280: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
b290: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
b2a0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
b2b0: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
b2c0: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
b2d0: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
b2e0: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
b2f0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
b300: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
b310: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
b320: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
b330: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
b340: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
b350: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
b360: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
b370: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
b380: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
b390: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
b3a0: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
b3b0: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
b3c0: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
b3d0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
b3e0: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
b3f0: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
b400: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
b410: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
b420: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
b430: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
b440: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
b450: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
b460: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
b470: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
b480: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
b490: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
b4a0: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
b4b0: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
b4c0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
b4d0: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
b4e0: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
b4f0: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
b500: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
b510: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
b520: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
b530: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
b540: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
b550: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
b560: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
b570: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
b580: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
b590: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
b5a0: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
b5b0: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
b5c0: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
b5d0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
b5e0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
b5f0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
b600: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
b610: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
b620: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
b630: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
b640: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
b650: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
b660: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
b670: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
b680: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
b690: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
b6a0: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
b6b0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
b6c0: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
b6d0: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
b6e0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
b6f0: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
b700: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
b710: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
b720: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
b730: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
b740: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
b750: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
b760: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
b770: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
b780: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
b790: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
b7a0: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
b7b0: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
b7c0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
b7d0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
b7e0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
b7f0: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
b800: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
b810: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
b820: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
b830: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
b840: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
b850: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
b860: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
b870: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b880: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
b890: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
b8a0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
b8b0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
b8c0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
b8d0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
b8e0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
b8f0: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
b900: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
b910: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
b920: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
b930: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
b940: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
b950: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
b960: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
b970: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b980: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b990: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
b9a0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
b9b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b9c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b9d0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
b9e0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
b9f0: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
ba00: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
ba10: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ba20: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
ba30: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
ba40: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
ba50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ba60: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
ba70: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
ba80: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
ba90: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
baa0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
bab0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
bac0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
bad0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
bae0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
baf0: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
bb00: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
bb10: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
bb20: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
bb30: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
bb40: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
bb50: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
bb60: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
bb70: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
bb80: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
bb90: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
bba0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
bbb0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
bbc0: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
bbd0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
bbe0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
bbf0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
bc00: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
bc10: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
bc20: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
bc30: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
bc40: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
bc50: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
bc60: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
bc70: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
bc80: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
bc90: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
bca0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
bcb0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
bcc0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
bcd0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
bce0: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
bcf0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
bd00: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
bd10: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
bd20: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
bd30: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
bd40: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
bd50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
bd60: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
bd70: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
bd80: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
bd90: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
bda0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
bdb0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
bdc0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
bdd0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
bde0: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
bdf0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
be00: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
be10: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
be20: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
be30: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
be40: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
be50: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
be60: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
be70: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
be80: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
be90: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
bea0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
beb0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
bec0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
bed0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
bee0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
bef0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
bf00: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
bf10: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
bf20: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
bf30: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
bf40: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
bf50: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
bf60: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
bf70: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
bf80: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
bf90: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
bfa0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
bfb0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
bfc0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
bfd0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
bfe0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
bff0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
c000: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
c010: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
c020: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
c030: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
c040: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
c050: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
c060: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
c070: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
c080: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
c090: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
c0a0: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
c0b0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
c0c0: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
c0d0: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
c0e0: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
c0f0: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
c100: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
c110: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
c120: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
c130: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
c140: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
c150: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
c160: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
c170: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
c180: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
c190: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
c1a0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
c1b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
c1c0: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
c1d0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
c1e0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
c1f0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
c200: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
c210: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
c220: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
c230: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
c240: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
c250: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
c260: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
c270: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
c280: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
c290: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
c2a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
c2b0: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
c2c0: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
c2d0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
c2e0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
c2f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
c300: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
c310: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
c320: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
c330: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
c340: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
c350: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
c360: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
c370: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
c380: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
c390: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
c3a0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
c3b0: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
c3c0: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
c3d0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
c3e0: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
c3f0: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
c400: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
c410: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
c420: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c430: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
c440: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
c450: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
c460: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
c470: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
c480: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
c490: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
c4a0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
c4b0: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
c4c0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
c4d0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
c4e0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
c4f0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
c500: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
c510: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
c520: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
c530: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
c540: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
c550: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
c560: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
c570: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
c580: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
c590: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
c5a0: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
c5b0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
c5c0: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
c5d0: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
c5e0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
c5f0: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
c600: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
c610: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
c620: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
c630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
c640: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
c650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
c660: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
c670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c680: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
c690: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
c6a0: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
c6b0: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
c6c0: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
c6d0: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
c6e0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
c6f0: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
c700: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
c710: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
c720: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
c730: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
c740: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
c750: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
c760: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
c770: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
c780: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
c790: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
c7a0: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
c7b0: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
c7c0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
c7d0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
c7e0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
c7f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
c800: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
c810: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
c820: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
c830: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
c840: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
c850: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
c860: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
c870: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
c880: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
c890: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
c8a0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
c8b0: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
c8c0: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
c8d0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
c8e0: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
c8f0: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
c900: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
c910: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
c920: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
c930: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
c940: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
c950: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
c960: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
c970: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
c980: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
c990: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
c9a0: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
c9b0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
c9c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c9d0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
c9e0: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
c9f0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
ca00: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
ca10: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ca20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ca30: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
ca40: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
ca50: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
ca60: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
ca70: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
ca80: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
ca90: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
caa0: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
cab0: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
cac0: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
cad0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
cae0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
caf0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
cb00: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
cb10: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
cb20: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
cb30: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
cb40: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
cb50: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
cb60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
cb70: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
cb80: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
cb90: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
cba0: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
cbb0: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
cbc0: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
cbd0: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
cbe0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cbf0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
cc00: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
cc10: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
cc20: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
cc30: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
cc40: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
cc50: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
cc60: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
cc70: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
cc80: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
cc90: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
cca0: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
ccb0: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
ccc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
ccd0: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
cce0: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
ccf0: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
cd00: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
cd10: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
cd20: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
cd30: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
cd40: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
cd50: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
cd60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
cd70: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
cd80: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
cd90: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
cda0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
cdb0: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
cdc0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
cdd0: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
cde0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
cdf0: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
ce00: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
ce10: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
ce20: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
ce30: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
ce40: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
ce50: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
ce60: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
ce70: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
ce80: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
ce90: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
cea0: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
ceb0: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
cec0: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
ced0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
cee0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
cef0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
cf00: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
cf10: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
cf20: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
cf30: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
cf40: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
cf50: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
cf60: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
cf70: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
cf80: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
cf90: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
cfa0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
cfb0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
cfc0: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
cfd0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
cfe0: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
cff0: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
d000: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
d010: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
d020: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
d030: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
d040: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
d050: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
d060: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
d070: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
d080: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
d090: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
d0a0: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
d0b0: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
d0c0: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
d0d0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
d0e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
d0f0: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
d100: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
d110: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
d120: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
d130: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
d140: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
d150: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
d160: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
d170: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
d180: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
d190: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
d1a0: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
d1b0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
d1c0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
d1d0: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
d1e0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
d1f0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
d200: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
d210: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
d220: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
d230: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
d240: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
d250: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
d260: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
d270: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
d280: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
d290: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
d2a0: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
d2b0: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
d2c0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
d2d0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
d2e0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
d2f0: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
d300: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
d310: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
d320: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
d330: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
d340: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
d350: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
d360: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
d370: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
d380: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
d390: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
d3a0: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
d3b0: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
d3c0: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
d3d0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
d3e0: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
d3f0: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
d400: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
d410: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
d420: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
d430: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
d440: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
d450: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
d460: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
d470: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
d480: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
d490: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
d4a0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
d4b0: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
d4c0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
d4d0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
d4e0: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
d4f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
d500: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
d510: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
d520: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
d530: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d540: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
d550: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
d560: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
d570: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
d580: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
d590: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
d5a0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
d5b0: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
d5c0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
d5d0: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
d5e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
d5f0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
d600: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
d610: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
d620: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
d630: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
d640: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
d650: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
d660: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
d670: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
d680: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
d690: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
d6a0: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
d6b0: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
d6c0: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
d6d0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
d6e0: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
d6f0: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
d700: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
d710: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
d720: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
d730: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
d740: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
d750: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
d760: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
d770: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
d780: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
d790: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
d7a0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
d7b0: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
d7c0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
d7d0: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
d7e0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
d7f0: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
d800: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
d810: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
d820: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
d830: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
d840: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
d850: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d860: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
d870: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
d880: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
d890: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
d8a0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
d8b0: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
d8c0: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
d8d0: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
d8e0: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
d8f0: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
d900: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
d910: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
d920: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
d930: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
d940: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
d950: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
d960: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
d970: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
d980: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
d990: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
d9a0: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
d9b0: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
d9c0: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
d9d0: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
d9e0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
d9f0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
da00: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
da10: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
da20: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
da30: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
da40: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
da50: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
da60: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
da70: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
da80: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
da90: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
daa0: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
dab0: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
dac0: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
dad0: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
dae0: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
daf0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
db00: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
db10: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
db20: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
db30: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
db40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
db50: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
db60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
db70: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
db80: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
db90: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
dba0: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
dbb0: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
dbc0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
dbd0: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
dbe0: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
dbf0: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
dc00: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
dc10: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
dc20: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
dc30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
dc40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
dc50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
dc60: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
dc70: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
dc80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dc90: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
dca0: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
dcb0: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
dcc0: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
dcd0: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
dce0: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
dcf0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
dd00: 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
dd10: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** 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 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
dd40: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
dd50: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
dd60: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
dd70: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
dd80: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
dd90: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
dda0: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
ddb0: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
ddc0: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
ddd0: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
dde0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
ddf0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
de00: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
de10: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
de20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
de30: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
de40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
de50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
de60: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
de70: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
de80: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
de90: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
dea0: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
deb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
dec0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
ded0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
dee0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
def0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
df00: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
df10: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
df20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
df30: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
df40: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
df50: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
df60: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
df70: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
df80: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
df90: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
dfa0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
dfb0: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
dfc0: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
dfd0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
dfe0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
dff0: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
e000: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
e010: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
e020: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
e030: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
e040: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
e050: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
e060: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
e070: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
e080: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
e090: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
e0a0: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
e0b0: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
e0c0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
e0d0: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
e0e0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
e0f0: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
e100: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
e110: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
e120: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
e130: 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
e140: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
e150: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
e160: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
e170: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
e180: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
e190: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e1a0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
e1b0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
e1c0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
e1d0: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
e1e0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
e1f0: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
e200: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
e210: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
e220: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
e230: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e240: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
e250: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
e260: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
e270: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
e280: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
e290: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
e2a0: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
e2b0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
e2c0: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
e2d0: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
e2e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
e2f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
e300: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
e310: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
e320: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
e330: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
e340: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
e350: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
e360: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
e370: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
e380: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
e390: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
e3a0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
e3b0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
e3c0: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
e3d0: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
e3e0: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
e3f0: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
e400: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
e410: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
e420: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
e430: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
e440: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
e450: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
e460: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
e470: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
e480: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
e490: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
e4a0: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
e4b0: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
e4c0: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
e4d0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
e4e0: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
e4f0: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
e500: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
e510: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
e520: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
e530: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
e540: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
e550: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
e560: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
e570: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
e580: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
e590: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
e5a0: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
e5b0: 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
e5c0: 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
e5d0: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
e5e0: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
e5f0: 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
e600: 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
e610: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
e620: 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
e630: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
e640: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
e650: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
e660: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
e670: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
e680: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
e690: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
e6a0: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
e6b0: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
e6c0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
e6d0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
e6e0: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
e6f0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
e700: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
e710: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
e720: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
e730: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
e740: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
e750: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
e760: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
e770: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
e780: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
e790: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
e7a0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
e7b0: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
e7c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
e7d0: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
e7e0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
e7f0: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
e800: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
e810: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
e820: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
e830: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
e840: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
e850: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
e860: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
e870: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
e880: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
e890: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
e8a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
e8b0: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
e8c0: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
e8d0: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
e8e0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
e8f0: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
e900: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
e910: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
e920: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
e930: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
e940: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
e950: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
e960: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
e970: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
e980: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
e990: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
e9a0: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
e9b0: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
e9c0: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
e9d0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
e9e0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
e9f0: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
ea00: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
ea10: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
ea20: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
ea30: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ea40: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
ea50: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
ea60: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
ea70: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
ea80: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
ea90: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
eaa0: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
eab0: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
eac0: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
ead0: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
eae0: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
eaf0: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
eb00: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
eb10: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
eb20: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
eb30: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
eb40: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
eb50: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
eb60: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
eb70: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
eb80: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
eb90: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
eba0: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
ebb0: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
ebc0: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
ebd0: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
ebe0: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
ebf0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
ec00: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
ec10: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
ec20: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
ec30: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
ec40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ec50: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
ec60: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
ec70: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
ec80: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
ec90: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
eca0: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
ecb0: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
ecc0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
ecd0: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
ece0: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
ecf0: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
ed00: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
ed10: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
ed20: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
ed30: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
ed40: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
ed50: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
ed60: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
ed70: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
ed80: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
ed90: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
eda0: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
edb0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
edc0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
edd0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
ede0: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
edf0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
ee00: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
ee10: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
ee20: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
ee30: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
ee40: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
ee50: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
ee60: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
ee70: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
ee80: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
ee90: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
eea0: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
eeb0: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
eec0: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
eed0: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
eee0: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
eef0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
ef00: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
ef10: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
ef20: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
ef30: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
ef40: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
ef50: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
ef60: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
ef70: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
ef80: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
ef90: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
efa0: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
efb0: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
efc0: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
efd0: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
efe0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
eff0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
f000: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
f010: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
f020: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
f030: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
f040: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
f050: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
f060: 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
f070: 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
f080: 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
f090: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
f0a0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
f0b0: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
f0c0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
f0d0: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
f0e0: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
f0f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
f100: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f110: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
f120: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
f130: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
f140: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
f150: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
f160: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
f170: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
f180: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
f190: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
f1a0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
f1b0: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
f1c0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
f1d0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
f1e0: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
f1f0: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
f200: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
f210: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
f220: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
f230: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
f240: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
f250: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
f260: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
f270: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
f280: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
f290: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
f2a0: 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
f2b0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
f2c0: 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
f2d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
f2e0: 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
f2f0: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
f300: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
f310: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
f320: 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
f330: 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
f340: 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
f350: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
f360: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
f370: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
f380: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
f390: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
f3a0: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
f3b0: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
f3c0: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
f3d0: 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
f3e0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
f3f0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
f400: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
f410: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
f420: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f430: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
f440: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
f450: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
f460: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
f470: 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
f480: 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
f490: 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
f4a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f4b0: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
f4c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
f4d0: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
f4e0: 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
f4f0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
f500: 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
f510: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
f520: 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
f530: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
f540: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
f550: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
f560: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
f570: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
f580: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
f590: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
f5a0: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
f5b0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
f5c0: 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
f5d0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
f5e0: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
f5f0: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
f600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f610: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
f620: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
f630: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
f640: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
f650: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
f660: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
f670: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
f680: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
f690: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
f6a0: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
f6b0: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
f6c0: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
f6d0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
f6e0: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
f6f0: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
f700: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
f710: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
f720: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
f730: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
f740: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
f750: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
f760: 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
f770: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
f780: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
f790: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f7a0: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
f7b0: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
f7c0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
f7d0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
f7e0: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
f7f0: 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
f800: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
f810: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
f820: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
f830: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
f840: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
f850: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
f860: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
f870: 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
f880: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
f890: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
f8a0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
f8b0: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
f8c0: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
f8d0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
f8e0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
f8f0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
f900: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
f910: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
f920: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
f930: 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
f940: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
f950: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
f960: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
f970: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
f980: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
f990: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
f9a0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
f9b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
f9c0: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
f9d0: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
f9e0: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
f9f0: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
fa00: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
fa10: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
fa20: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
fa30: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
fa40: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
fa50: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
fa60: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fa70: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
fa80: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
fa90: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
faa0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
fab0: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
fac0: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
fad0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
fae0: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
faf0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
fb00: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
fb10: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
fb20: 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
fb30: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
fb40: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
fb50: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
fb60: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
fb70: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
fb80: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
fb90: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
fba0: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
fbb0: 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
fbc0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
fbd0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
fbe0: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
fbf0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
fc00: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
fc10: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
fc20: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
fc30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fc40: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
fc50: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
fc60: 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
fc70: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
fc80: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
fc90: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
fca0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
fcb0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
fcc0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
fcd0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
fce0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
fcf0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
fd00: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
fd10: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
fd20: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
fd30: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
fd40: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
fd50: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
fd60: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
fd70: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
fd80: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
fd90: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
fda0: 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
fdb0: 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
fdc0: 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
fdd0: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
fde0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
fdf0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
fe00: 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
fe10: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
fe20: 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
fe30: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
fe40: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
fe50: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fe60: 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
fe70: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
fe80: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
fe90: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
fea0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
feb0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
fec0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
fed0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
fee0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
fef0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
ff00: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
ff10: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
ff20: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
ff30: 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
ff40: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
ff50: 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
ff60: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
ff70: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
ff80: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
ff90: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
ffa0: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
ffb0: 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
ffc0: 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
ffd0: 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
ffe0: 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
fff0: 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
10000 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
10010 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10020 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
10030 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10040 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
10050 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
10060 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
10070 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
10080 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
10090 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
100a0 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
100b0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
100c0 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
100d0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
100e0 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
100f0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
10100 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
10110 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
10120 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
10130 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
10140 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
10150 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
10160 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
10170 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
10180 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
10190 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
101a0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
101b0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
101c0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
101d0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
101e0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
101f0 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
10200 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
10210 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
10220 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
10230 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
10240 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
10250 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
10260 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
10270 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
10280 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
10290 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
102a0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
102b0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
102c0 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
102d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
102e0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
102f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10300 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
10310 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
10320 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
10330 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
10340 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
10350 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
10360 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
10370 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
10380 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
10390 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
103a0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
103b0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
103c0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
103d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
103e0 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
103f0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
10400 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
10410 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
10420 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
10430 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
10440 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
10450 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
10460 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
10470 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
10480 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10490 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
104a0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
104b0 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
104c0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
104d0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
104e0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
104f0 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
10500 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
10510 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
10520 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
10530 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
10540 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
10550 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
10560 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
10570 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
10580 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
10590 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
105a0 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
105b0 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
105c0 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
105d0 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
105e0 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
105f0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
10600 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
10610 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
10620 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
10630 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
10640 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
10650 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
10660 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
10670 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
10680 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
10690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
106a0 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
106b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
106c0 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
106d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
106e0 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
106f0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
10700 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
10710 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
10720 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
10730 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
10740 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
10750 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
10760 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
10770 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
10780 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
10790 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
107a0 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
107b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
107c0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
107d0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
107e0 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
107f0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
10800 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
10810 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
10820 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
10830 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
10840 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
10850 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
10860 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
10870 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
10880 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
10890 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
108a0 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
108b0 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
108c0 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
108d0 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
108e0 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
108f0 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
10900 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
10910 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
10920 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
10930 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
10940 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
10950 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
10960 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
10970 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
10980 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
10990 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
109a0 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
109b0 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
109c0 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
109d0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
109e0 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
109f0 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
10a00 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
10a10 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
10a20 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
10a30 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
10a40 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
10a50 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
10a60 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
10a70 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
10a80 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
10a90 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
10aa0 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
10ab0 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
10ac0 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
10ad0 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
10ae0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
10af0 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
10b00 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
10b10 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
10b20 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
10b30 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
10b40 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f  space..** The po
10b50 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
10b60 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
10b70 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
10b80 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
10b90 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
10ba0 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
10bb0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
10bc0 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
10bd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10be0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
10bf0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10c00 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
10c10 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
10c20 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
10c30 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
10c40 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
10c50 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
10c60 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
10c70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10c80 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
10c90 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
10ca0 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
10cb0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
10cc0 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
10cd0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
10ce0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
10cf0 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
10d00 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
10d10 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
10d20 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
10d30 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
10d40 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
10d50 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
10d60 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
10d70 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
10d80 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
10d90 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
10da0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
10db0 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
10dc0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
10dd0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
10de0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
10df0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
10e00 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
10e10 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
10e20 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
10e30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10e40 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
10e50 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
10e60 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
10e70 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
10e80 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
10e90 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
10ea0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
10eb0 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
10ec0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
10ed0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
10ee0 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
10ef0 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
10f00 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
10f10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
10f20 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
10f30 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
10f40 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
10f50 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
10f60 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
10f70 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
10f80 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
10f90 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
10fa0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
10fb0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
10fc0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
10fd0 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
10fe0 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
10ff0 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
11000 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
11010 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
11020 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
11030 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11040 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
11050 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
11060 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
11070 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11080 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11090 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
110a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
110b0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
110c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
110d0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
110e0 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
110f0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
11100 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
11110 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
11120 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
11130 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
11140 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
11150 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11160 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
11170 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
11180 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
11190 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
111a0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
111b0 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
111c0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
111d0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
111e0 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
111f0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11200 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11210 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11220 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11230 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11240 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11250 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
11260 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
11270 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
11280 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
11290 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
112a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
112b0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
112c0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
112d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
112e0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
112f0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
11300 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
11310 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11320 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
11330 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
11340 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
11350 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11360 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11370 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
11380 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
11390 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
113a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
113b0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
113c0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
113d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
113e0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
113f0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
11400 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
11410 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
11420 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
11430 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
11440 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
11450 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
11460 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
11470 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
11480 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
11490 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
114a0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
114b0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
114c0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
114d0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
114e0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
114f0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11500 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11510 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11520 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11530 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11540 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
11550 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
11560 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
11570 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
11580 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
11590 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
115a0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
115b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
115c0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
115d0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
115e0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
115f0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
11600 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11610 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
11620 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11630 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
11640 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
11650 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
11660 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
11670 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
11680 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
11690 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
116a0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
116b0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
116c0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
116d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
116e0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
116f0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
11700 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
11710 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
11720 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
11730 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
11740 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
11750 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
11760 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
11770 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
11780 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
11790 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
117a0 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
117b0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
117c0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
117d0 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
117e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
117f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
11800 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
11810 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
11820 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
11830 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
11840 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
11860 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
11870 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
11880 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11890 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
118a0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
118b0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
118c0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
118d0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
118e0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
118f0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
11900 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
11910 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
11920 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
11930 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
11940 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
11950 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
11960 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
11970 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
11980 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
11990 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
119a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
119b0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
119c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
119d0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
119e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
119f0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
11a00 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11a10 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
11a20 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
11a30 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
11a40 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
11a50 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
11a60 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
11a70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
11a80 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
11a90 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
11aa0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11ab0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
11ac0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11ad0 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
11ae0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
11af0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
11b00 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
11b10 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
11b20 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
11b30 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
11b40 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
11b50 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
11b60 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
11b70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
11b80 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
11b90 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
11ba0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
11bb0 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
11bc0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
11bd0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
11be0 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
11bf0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
11c00 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
11c10 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
11c20 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
11c30 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
11c40 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
11c50 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
11c60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11c70 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
11c80 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
11c90 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
11ca0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
11cb0 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
11cc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
11cd0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
11ce0 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
11cf0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
11d00 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
11d10 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
11d20 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
11d30 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
11d40 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
11d50 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
11d60 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
11d70 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
11d80 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
11d90 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
11da0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
11db0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
11dc0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
11dd0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
11de0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
11df0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
11e00 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
11e10 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
11e20 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
11e30 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
11e40 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
11e50 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
11e60 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
11e70 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
11e80 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
11e90 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
11ea0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
11eb0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
11ec0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
11ed0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
11ee0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
11ef0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
11f00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
11f10 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
11f20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
11f30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
11f40 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11f50 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
11f60 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b   This option tak
11f70 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
11f80 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
11f90 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  . If non-zero, t
11fa0 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c  hen.** URI handl
11fb0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
11fc0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
11fd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
11fe0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
11ff0 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61  ling.** is globa
12000 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66  lly disabled. If
12010 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
12020 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
12030 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
12040 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73  .** passed to [s
12050 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
12060 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
12070 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
12080 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
12090 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
120a0 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
120b0 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
120c0 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
120d0 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
120e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
120f0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
12100 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
12110 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
12120 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
12130 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74  is opened. If it
12140 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
12150 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
12160 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
12170 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
12180 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
12190 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
121a0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
121b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
121c0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42  ion is opened. B
121d0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
121e0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
121f0 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
12200 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
12210 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
12220 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
12230 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
12240 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
12250 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ol defined..**.*
12260 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12270 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
12280 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
12290 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
122a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
122b0 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
122c0 4e 46 4e 49 47 5f 47 45 54 50 43 41 43 48 45 0a  NFNIG_GETPCACHE.
122d0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
122e0 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
122f0 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
12300 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
12310 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
12320 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
12330 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
12340 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
12350 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
12360 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
12370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
12380 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
12390 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
123a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
123b0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
123c0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
123d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
123e0 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
123f0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
12400 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12410 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
12420 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
12430 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
12440 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12450 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
12460 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
12470 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
12480 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12490 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
124a0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
124b0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
124c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
124d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
124e0 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
124f0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
12500 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12510 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
12520 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
12530 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
12540 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
12550 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12560 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
12570 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
12580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12590 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
125a0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
125b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
125c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
125d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
125e0 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
125f0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12600 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
12610 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
12620 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
12630 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
12640 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
12650 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12660 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
12670 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
12680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12690 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
126a0 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
126b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
126c0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
126d0 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
126e0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
126f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
12700 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
12710 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
12720 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12730 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
12740 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
12750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12760 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
12770 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
12780 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
12790 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
127a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
127b0 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
127c0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
127d0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a  ethods2* */../*.
127e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
127f0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
12800 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
12810 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
12820 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
12830 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
12840 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
12850 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
12860 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
12870 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
12880 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
12890 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
128a0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
128b0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
128c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
128d0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
128e0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
128f0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
12900 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
12910 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
12920 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
12930 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
12940 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
12950 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
12960 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
12970 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
12980 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
12990 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
129a0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
129b0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
129c0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
129d0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
129e0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
129f0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
12a00 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
12a10 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
12a20 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
12a30 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
12a40 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
12a50 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
12a60 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
12a70 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
12a80 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
12a90 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
12aa0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
12ab0 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
12ac0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12ad0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
12ae0 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
12af0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
12b00 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
12b10 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
12b20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
12b30 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12b40 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
12b50 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
12b60 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
12b70 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
12b80 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
12b90 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
12ba0 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
12bb0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
12bc0 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
12bd0 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
12be0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
12bf0 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
12c00 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
12c10 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
12c20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
12c30 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
12c40 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
12c50 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
12c60 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
12c70 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
12c80 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
12c90 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
12ca0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
12cb0 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
12cc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12cd0 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
12ce0 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
12cf0 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
12d00 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
12d10 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
12d20 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
12d30 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
12d40 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
12d50 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
12d60 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12d70 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
12d80 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12d90 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
12da0 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
12db0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
12dc0 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
12dd0 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
12de0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
12df0 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
12e00 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
12e10 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
12e20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12e30 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
12e40 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
12e50 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
12e60 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
12e70 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
12e80 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
12e90 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
12ea0 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
12eb0 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
12ec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
12ed0 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
12ee0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
12ef0 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
12f00 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
12f10 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
12f20 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
12f30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
12f40 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
12f50 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
12f60 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
12f70 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
12f80 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
12f90 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
12fa0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
12fb0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
12fc0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
12fd0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
12fe0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
12ff0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
13000 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
13010 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
13020 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
13030 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
13040 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
13050 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
13060 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
13070 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
13080 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
13090 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
130a0 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
130b0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
130c0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
130d0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
130e0 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
130f0 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
13100 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
13110 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
13120 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
13130 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
13140 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
13150 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
13160 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
13170 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
13180 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
13190 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
131a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
131b0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
131c0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
131d0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
131e0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
131f0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
13200 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
13210 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
13220 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
13230 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
13240 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
13250 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
13260 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
13270 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
13280 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
13290 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
132a0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
132b0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
132c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
132d0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
132e0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
132f0 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
13300 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
13310 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
13320 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
13330 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
13340 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
13350 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13360 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
13370 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
13380 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
13390 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
133a0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
133b0 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
133c0 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
133d0 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
133e0 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
133f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13400 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
13410 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
13420 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
13430 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
13440 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
13450 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  . </dd>.**.** </
13460 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
13470 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
13480 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31  OOKASIDE       1
13490 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
134a0 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
134b0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
134c0 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20  _ENABLE_FKEY    
134d0 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e   1002  /* int in
134e0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
134f0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
13500 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30  ABLE_TRIGGER  10
13510 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  03  /* int int* 
13520 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
13530 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
13540 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
13550 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a  Result Codes.**.
13560 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
13570 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
13580 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
13590 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
135a0 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
135b0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
135c0 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
135d0 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
135e0 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
135f0 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
13600 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
13610 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
13620 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
13630 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
13640 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
13650 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
13660 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
13670 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
13680 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45  t Rowid.**.** ^E
13690 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
136a0 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
136b0 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
136c0 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
136d0 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
136e0 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
136f0 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
13700 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
13710 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
13720 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
13730 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
13740 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
13750 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
13760 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
13770 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
13780 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
13790 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
137a0 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
137b0 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
137c0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
137d0 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
137e0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
137f0 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
13800 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
13810 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
13820 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
13830 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
13840 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
13850 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74   [INSERT] into t
13860 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
13870 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
13880 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  onnection].** in
13890 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
138a0 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c  ent.  ^As of SQL
138b0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
138c0 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73  7, this routines
138d0 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20  .** records the 
138e0 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
138f0 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61  d of both ordina
13900 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76  ry tables and [v
13910 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a  irtual tables]..
13920 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  ** ^If no succes
13930 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a  sful [INSERT]s.*
13940 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
13950 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
13960 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13970 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
13980 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ed..**.** ^(If a
13990 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
139a0 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
139b0 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
139c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
139d0 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
139e0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
139f0 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
13a00 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
13a10 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
13a20 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
13a30 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
13a40 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
13a50 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
13a60 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
13a70 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
13a80 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
13a90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
13aa0 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
13ab0 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
13ac0 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
13ad0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
13ae0 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
13af0 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
13b00 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
13b10 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
13b20 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
13b30 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
13b40 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
13b50 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
13b60 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
13b70 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
13b80 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
13b90 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
13ba0 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
13bb0 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
13bc0 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
13bd0 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
13be0 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
13bf0 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
13c00 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
13c10 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
13c20 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
13c30 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
13c40 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
13c50 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
13c60 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
13c70 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
13c80 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
13c90 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
13ca0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
13cb0 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
13cc0 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
13cd0 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
13ce0 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
13cf0 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
13d00 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
13d10 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
13d20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
13d30 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
13d40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
13d50 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
13d60 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
13d70 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
13d80 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
13d90 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
13da0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
13db0 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
13dc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
13dd0 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
13de0 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
13df0 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
13e00 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
13e10 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
13e20 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
13e30 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
13e40 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
13e50 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
13e60 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
13e70 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
13e80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
13e90 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
13ea0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
13eb0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
13ec0 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
13ed0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
13ee0 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
13ef0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
13f00 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
13f10 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
13f20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
13f30 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
13f40 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
13f50 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
13f60 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
13f70 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
13f80 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
13f90 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
13fa0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
13fb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13fc0 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
13fd0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
13fe0 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
13ff0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
14000 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
14010 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
14020 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
14030 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
14040 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
14050 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
14060 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
14070 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
14080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14090 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
140a0 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
140b0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
140c0 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
140d0 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
140e0 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
140f0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
14100 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
14110 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
14120 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
14130 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
14140 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
14150 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
14160 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
14170 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
14180 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
14190 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
141a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
141b0 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
141c0 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
141d0 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
141e0 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
141f0 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
14200 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
14210 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
14220 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
14230 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
14240 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
14250 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
14260 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
14270 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
14280 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
14290 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
142a0 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
142b0 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
142c0 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
142d0 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
142e0 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
142f0 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
14300 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
14310 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
14320 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
14330 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
14340 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
14350 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
14360 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
14370 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
14380 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
14390 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
143a0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
143b0 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
143c0 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
143d0 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
143e0 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
143f0 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
14400 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
14410 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
14420 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
14430 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
14440 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
14450 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
14460 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
14470 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
14480 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
14490 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
144a0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
144b0 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
144c0 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
144d0 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
144e0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
144f0 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
14500 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
14510 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
14520 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
14530 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
14540 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
14550 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
14560 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
14570 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
14580 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
14590 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
145a0 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
145b0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
145c0 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
145d0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
145e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
145f0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
14600 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
14610 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
14620 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
14630 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
14640 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
14650 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
14660 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
14670 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
14680 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
14690 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
146a0 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
146b0 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
146c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
146d0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
146e0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
146f0 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
14700 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
14710 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
14720 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
14730 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
14740 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
14750 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
14760 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
14770 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
14780 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
14790 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
147a0 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
147b0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
147c0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
147d0 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
147e0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
147f0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
14800 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
14810 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
14820 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
14830 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
14840 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
14850 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
14860 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
14870 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
14880 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
14890 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
148a0 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
148b0 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
148c0 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
148d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
148e0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
148f0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
14900 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
14910 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
14920 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
14930 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
14940 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
14950 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
14960 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
14970 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
14980 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
14990 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
149a0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
149b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
149c0 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
149d0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
149e0 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
149f0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
14a00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
14a10 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
14a20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20  by [INSERT],.** 
14a30 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
14a40 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
14a50 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
14a60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14a70 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e  was opened..** ^
14a80 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72  (The count retur
14a90 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
14aa0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69  otal_changes() i
14ab0 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
14ac0 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20  ges.** from all 
14ad0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
14ae0 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65  | trigger] conte
14af0 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20  xts and changes 
14b00 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65  made by.** [fore
14b10 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
14b20 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68  . However,.** th
14b30 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  e count does not
14b40 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
14b50 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
14b60 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  nt [REPLACE] con
14b70 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
14b80 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
14b90 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
14ba0 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70  r [DROP TABLE] p
14bb0 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a  rocessing.  The.
14bc0 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  ** count does no
14bd0 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f  t include rows o
14be0 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72  f views that fir
14bf0 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  e an [INSTEAD OF
14c00 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68   trigger],.** th
14c10 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54  ough if the INST
14c20 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d  EAD OF trigger m
14c30 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20  akes changes of 
14c40 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63  its own, those c
14c50 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63  hanges .** are c
14c60 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68  ounted.)^.** ^Th
14c70 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  e sqlite3_total_
14c80 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
14c90 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68  on counts the ch
14ca0 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73  anges as soon as
14cb0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
14cc0 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
14cd0 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28  m is completed (
14ce0 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
14cf0 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  nt handle.** is 
14d00 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
14d10 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
14d20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
14d30 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
14d40 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
14d50 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
14d60 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
14d70 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
14d80 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
14d90 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
14da0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
14db0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
14dc0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
14dd0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
14de0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
14df0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
14e00 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
14e10 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
14e20 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
14e30 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
14e40 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
14e50 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
14e60 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
14e70 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
14e80 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
14e90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
14ea0 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
14eb0 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
14ec0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
14ed0 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
14ee0 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
14ef0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
14f00 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
14f10 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
14f20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
14f30 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
14f40 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
14f50 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
14f60 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
14f70 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
14f80 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
14f90 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
14fa0 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
14fb0 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
14fc0 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
14fd0 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
14fe0 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
14ff0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
15000 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
15010 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
15020 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
15030 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
15040 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
15050 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
15060 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
15070 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
15080 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
15090 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
150a0 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
150b0 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
150c0 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
150d0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
150e0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
150f0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
15100 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
15110 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
15120 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
15130 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
15140 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
15150 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
15160 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
15170 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
15180 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
15190 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
151a0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
151b0 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
151c0 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
151d0 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
151e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
151f0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
15200 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
15210 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
15220 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
15230 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
15240 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
15250 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
15260 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
15270 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
15280 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
15290 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
152a0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
152b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
152c0 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
152d0 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
152e0 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
152f0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
15300 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
15310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15320 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
15330 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
15340 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
15350 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
15360 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
15370 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
15380 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
15390 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
153a0 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
153b0 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
153c0 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
153d0 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
153e0 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
153f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
15400 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
15410 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
15420 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
15430 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
15440 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
15450 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
15460 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
15470 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
15480 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
15490 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
154a0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
154b0 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
154c0 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
154d0 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
154e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
154f0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
15500 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
15510 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
15520 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
15530 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
15540 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
15550 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
15560 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
15570 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
15580 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
15590 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
155a0 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
155b0 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
155c0 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
155d0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
155e0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
155f0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
15600 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
15610 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
15620 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
15630 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
15640 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
15650 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
15660 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
15670 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
15680 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
15690 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
156a0 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
156b0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
156c0 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
156d0 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
156e0 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
156f0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
15700 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
15710 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
15720 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
15730 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
15740 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
15750 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
15760 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
15770 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
15780 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
15790 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
157a0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
157b0 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
157c0 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
157d0 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
157e0 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
157f0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
15800 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
15810 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
15820 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
15830 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
15840 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
15850 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
15860 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
15870 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
15880 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
15890 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
158a0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
158b0 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
158c0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
158d0 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
158e0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
158f0 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
15900 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
15910 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
15920 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
15930 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
15940 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
15950 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
15960 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
15970 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
15980 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
15990 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
159a0 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
159b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
159c0 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
159d0 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
159e0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
159f0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
15a00 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
15a10 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
15a20 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
15a30 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
15a40 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
15a50 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
15a60 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
15a70 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
15a80 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
15a90 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
15aa0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
15ab0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
15ac0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
15ad0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
15ae0 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
15af0 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
15b00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
15b10 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
15b20 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
15b30 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
15b40 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
15b50 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
15b60 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
15b70 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
15b80 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
15b90 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
15ba0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
15bb0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
15bc0 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
15bd0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
15be0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
15bf0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
15c00 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
15c10 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
15c20 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
15c30 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
15c40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
15c50 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
15c60 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
15c70 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
15c80 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
15c90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15ca0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
15cb0 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
15cc0 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
15cd0 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  rors.**.** ^This
15ce0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
15cf0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
15d00 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
15d10 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
15d20 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
15d30 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
15d40 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
15d50 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
15d60 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
15d70 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
15d80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
15d90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
15da0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
15db0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
15dc0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
15dd0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
15de0 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
15df0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
15e00 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
15e10 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
15e20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
15e30 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
15e40 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
15e50 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
15e60 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
15e70 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
15e80 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
15e90 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
15ea0 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
15eb0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
15ec0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
15ed0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
15ee0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
15ef0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15f00 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
15f10 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
15f20 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
15f30 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
15f40 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
15f50 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
15f60 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
15f70 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
15f80 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
15f90 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
15fa0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
15fb0 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
15fc0 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
15fd0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
15fe0 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
15ff0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
16000 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
16010 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  turned..** ^If t
16020 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
16030 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
16040 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
16050 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
16060 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
16070 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
16080 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
16090 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
160a0 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
160b0 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
160c0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
160d0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
160e0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
160f0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
16100 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
16110 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
16120 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
16130 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
16140 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
16150 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
16160 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
16170 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
16180 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
16190 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
161a0 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
161b0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
161c0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
161d0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
161e0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
161f0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
16200 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
16210 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
16220 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
16230 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
16240 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
16250 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
16260 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
16270 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
16280 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
16290 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
162a0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
162b0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
162c0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
162d0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
162e0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
162f0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
16300 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
16310 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
16320 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
16330 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
16340 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
16350 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
16360 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
16370 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
16380 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
16390 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
163a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
163b0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
163c0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
163d0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
163e0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
163f0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
16400 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
16410 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
16420 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
16430 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
16440 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
16450 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
16460 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
16470 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
16480 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
16490 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
164a0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
164b0 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
164c0 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
164d0 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
164e0 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
164f0 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
16500 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
16510 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
16520 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
16530 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
16540 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
16550 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
16560 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
16570 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
16580 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
16590 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
165a0 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
165b0 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
165c0 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
165d0 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
165e0 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
165f0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
16600 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e  s.  ^If it is un
16610 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
16620 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
16630 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
16640 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
16650 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
16660 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
16670 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
16680 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
16690 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
166a0 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
166b0 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
166c0 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
166d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
166e0 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65  OCKED].  ^This e
166f0 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
16700 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
16710 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
16720 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
16730 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
16740 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
16750 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
16760 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
16770 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
16780 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
16790 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
167a0 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
167b0 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
167c0 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
167d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  nt..**.** ^(Ther
167e0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
167f0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
16800 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
16810 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
16820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
16830 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
16840 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
16850 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
16860 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
16870 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
16880 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
16890 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
168a0 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
168b0 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
168c0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
168d0 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
168e0 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
168f0 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
16900 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
16910 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
16920 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
16930 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
16940 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
16950 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
16960 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
16970 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
16980 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
16990 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
169a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
169b0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
169c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
169d0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
169e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
169f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
16a00 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
16a10 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
16a20 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
16a30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16a40 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
16a50 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
16a60 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
16a70 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
16a80 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
16a90 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
16aa0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
16ab0 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
16ac0 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
16ad0 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
16ae0 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
16af0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
16b00 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
16b10 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
16b20 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
16b30 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
16b40 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
16b50 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
16b60 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
16b70 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
16b80 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
16b90 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
16ba0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16bb0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
16bc0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
16bd0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
16be0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
16bf0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
16c00 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
16c10 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
16c20 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
16c30 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
16c40 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
16c50 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
16c60 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
16c70 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
16c80 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
16c90 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
16ca0 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
16cb0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
16cc0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
16cd0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
16ce0 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
16cf0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
16d00 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
16d10 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
16d20 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
16d30 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
16d40 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
16d50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
16d60 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
16d70 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
16d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d90 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
16da0 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
16db0 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
16dc0 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
16dd0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
16de0 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
16df0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
16e00 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
16e10 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
16e20 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
16e30 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
16e40 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
16e50 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
16e60 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
16e70 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
16e80 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
16e90 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
16ea0 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
16eb0 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
16ec0 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
16ed0 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
16ee0 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
16ef0 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
16f00 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
16f10 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
16f20 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
16f30 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
16f40 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
16f50 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
16f60 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
16f70 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
16f80 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
16f90 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
16fa0 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
16fb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
16fc0 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
16fd0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
16fe0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
16ff0 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
17000 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
17010 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
17020 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
17030 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
17040 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
17050 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
17060 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
17070 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
17080 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17090 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
170a0 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
170b0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
170c0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
170d0 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
170e0 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
170f0 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
17100 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
17110 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
17120 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
17130 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
17140 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
17150 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
17160 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
17170 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
17180 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
17190 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
171a0 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
171b0 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
171c0 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
171d0 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
171e0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
171f0 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
17200 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
17210 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
17220 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
17230 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
17240 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
17250 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
17260 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
17270 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
17280 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
17290 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
172a0 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
172b0 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
172c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
172d0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
172e0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
172f0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
17300 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
17310 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
17320 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
17330 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
17340 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
17350 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
17360 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
17370 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
17380 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
17390 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
173a0 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
173b0 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
173c0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
173d0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
173e0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
173f0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
17400 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
17410 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
17420 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
17430 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
17440 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
17450 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
17460 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
17470 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
17480 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
17490 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
174a0 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
174b0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
174c0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
174d0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
174e0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
174f0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
17500 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
17510 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
17520 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
17530 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
17540 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
17550 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
17560 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
17570 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
17580 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
17590 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
175a0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
175b0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
175c0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
175d0 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
175e0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
175f0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
17600 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
17610 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
17620 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
17630 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
17640 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
17650 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
17660 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
17670 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
17680 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
17690 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
176a0 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
176b0 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
176c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
176d0 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
176e0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
176f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
17700 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
17710 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
17720 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
17730 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
17740 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
17750 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
17760 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17770 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
17780 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
17790 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
177a0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
177b0 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
177c0 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
177d0 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
177e0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
177f0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
17800 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
17810 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
17820 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
17830 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
17840 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
17850 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
17860 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
17870 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
17880 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
17890 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
178a0 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
178b0 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
178c0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
178d0 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
178e0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
178f0 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
17900 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
17910 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
17920 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
17930 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
17940 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
17950 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
17960 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
17970 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
17980 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
17990 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
179a0 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
179b0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
179c0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
179d0 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
179e0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
179f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
17a00 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
17a10 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
17a20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
17a30 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
17a40 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
17a50 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
17a60 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
17a70 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
17a80 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
17a90 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
17aa0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
17ab0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
17ac0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
17ad0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
17ae0 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
17af0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
17b00 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
17b10 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
17b20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
17b30 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
17b40 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
17b50 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
17b60 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
17b70 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
17b80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17b90 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
17ba0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
17bb0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
17bc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
17bd0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
17be0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
17bf0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
17c00 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
17c10 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
17c20 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
17c30 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
17c40 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
17c50 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
17c60 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
17c70 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
17c80 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
17c90 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17ca0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
17cb0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
17cc0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
17cd0 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
17ce0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
17cf0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
17d00 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
17d10 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
17d20 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
17d30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
17d40 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
17d50 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
17d60 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
17d70 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
17d80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
17d90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
17da0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
17db0 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
17dc0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
17dd0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
17de0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
17df0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
17e00 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
17e10 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
17e20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
17e30 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
17e40 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
17e50 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
17e60 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
17e70 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
17e80 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
17e90 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
17ea0 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
17eb0 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
17ec0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
17ed0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
17ee0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
17ef0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
17f00 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
17f10 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
17f20 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
17f30 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
17f40 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
17f50 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
17f60 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
17f70 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
17f80 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
17f90 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
17fa0 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
17fb0 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
17fc0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
17fd0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
17fe0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
17ff0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
18000 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
18010 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
18020 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
18030 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
18040 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
18050 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
18060 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
18070 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
18080 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
18090 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
180a0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
180b0 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
180c0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
180d0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
180e0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
180f0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
18100 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
18110 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
18120 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
18130 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
18140 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
18150 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
18160 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
18170 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
18180 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
18190 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
181a0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
181b0 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
181c0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
181d0 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
181e0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
181f0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
18200 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
18210 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
18220 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
18230 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
18240 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
18250 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
18260 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
18270 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
18280 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
18290 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
182a0 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
182b0 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
182c0 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
182d0 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
182e0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
182f0 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
18300 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
18310 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
18320 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
18330 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
18340 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
18350 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
18360 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
18370 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
18380 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
18390 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
183a0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
183b0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
183c0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
183d0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
183e0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
183f0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
18400 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
18410 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
18420 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
18430 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
18440 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
18450 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
18460 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
18470 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18480 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
18490 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
184a0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
184b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
184c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
184d0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
184e0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
184f0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
18500 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
18510 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
18520 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
18530 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
18540 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
18550 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
18560 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
18570 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
18580 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
18590 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
185a0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
185b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
185c0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
185d0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
185e0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
185f0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
18600 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
18610 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
18620 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
18630 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
18640 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
18650 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
18660 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
18670 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
18680 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
18690 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
186a0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
186b0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
186c0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
186d0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
186e0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
186f0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
18700 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
18710 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
18720 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
18730 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
18740 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
18750 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18760 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
18770 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
18780 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
18790 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
187a0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
187b0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
187c0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
187d0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
187e0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
187f0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
18800 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
18810 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
18820 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
18830 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
18840 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
18850 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
18860 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
18870 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
18880 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
18890 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
188a0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
188b0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
188c0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
188d0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
188e0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
188f0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
18900 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
18910 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
18920 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18930 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
18940 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
18950 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
18960 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
18970 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
18980 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
18990 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
189a0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
189b0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
189c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
189d0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
189e0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
189f0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
18a00 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
18a10 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
18a20 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
18a30 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
18a40 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
18a50 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
18a60 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
18a70 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
18a80 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
18a90 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
18aa0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
18ab0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
18ac0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
18ad0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
18ae0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
18af0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
18b00 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
18b10 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
18b20 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
18b30 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
18b40 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
18b50 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
18b60 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
18b70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
18b80 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
18b90 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  r*, ...);.char *
18ba0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
18bb0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
18bc0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
18bd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18be0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
18bf0 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
18c00 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
18c10 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
18c20 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
18c30 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
18c40 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
18c50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18c60 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
18c70 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
18c80 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
18c90 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
18ca0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
18cb0 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
18cc0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
18cd0 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
18ce0 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
18cf0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
18d00 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
18d10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
18d20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
18d30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
18d40 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
18d50 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
18d60 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
18d70 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
18d80 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
18d90 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
18da0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
18db0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
18dc0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
18dd0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
18de0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
18df0 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
18e00 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
18e10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
18e20 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
18e30 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
18e40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
18e50 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
18e60 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
18e70 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
18e80 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
18e90 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
18ea0 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
18eb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
18ec0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
18ed0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
18ee0 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
18ef0 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
18f00 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
18f10 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
18f20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
18f30 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
18f40 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
18f50 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
18f60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
18f70 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
18f80 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
18f90 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
18fa0 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
18fb0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
18fc0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
18fd0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
18fe0 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
18ff0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
19000 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
19010 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
19020 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
19030 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
19040 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
19050 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
19060 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
19070 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
19080 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
19090 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
190a0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
190b0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
190c0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
190d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
190e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
190f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
19100 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
19110 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19120 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
19130 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
19140 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
19150 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
19160 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
19170 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
19180 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
19190 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
191a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
191b0 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
191c0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
191d0 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
191e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
191f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
19200 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
19210 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
19220 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
19230 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
19240 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
19250 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
19260 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
19270 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
19280 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19290 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
192a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
192b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
192c0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
192d0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
192e0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
192f0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
19300 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
19310 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
19320 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
19330 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
19340 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19350 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
19360 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
19370 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
19380 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
19390 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
193a0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
193b0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
193c0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
193d0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
193e0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
193f0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
19400 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
19410 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
19420 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
19430 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
19440 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
19450 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
19460 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
19470 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
19480 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
19490 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
194a0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
194b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
194c0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
194d0 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
194e0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
194f0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
19500 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
19510 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
19520 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
19530 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
19540 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
19550 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
19560 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
19570 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
19580 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
19590 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
195a0 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
195b0 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
195c0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
195d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
195e0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
195f0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
19600 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
19610 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
19620 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
19630 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
19640 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
19650 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
19660 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
19670 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
19680 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
19690 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
196a0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
196b0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
196c0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
196d0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
196e0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
196f0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
19700 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
19710 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
19720 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
19730 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
19740 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
19750 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
19760 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
19770 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
19780 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
19790 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
197a0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
197b0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
197c0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
197d0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
197e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
197f0 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
19800 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
19810 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
19820 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
19830 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
19840 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
19850 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
19860 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
19870 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
19880 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
19890 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
198a0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
198b0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
198c0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
198d0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
198e0 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
198f0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
19900 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
19910 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
19920 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
19930 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
19940 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
19950 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
19960 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
19970 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
19980 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
19990 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
199a0 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
199b0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
199c0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
199d0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
199e0 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
199f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
19a00 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
19a10 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
19a20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
19a30 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
19a40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19a50 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
19a60 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
19a70 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
19a80 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
19a90 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
19aa0 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
19ab0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
19ac0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19ad0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
19ae0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
19af0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
19b00 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
19b10 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
19b20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19b30 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
19b40 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
19b50 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
19b60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
19b70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
19b80 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
19b90 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
19ba0 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
19bb0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
19bc0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
19bd0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
19be0 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
19bf0 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
19c00 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
19c10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
19c20 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
19c30 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
19c40 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
19c50 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
19c60 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
19c70 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
19c80 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
19c90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
19ca0 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
19cb0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
19cc0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
19cd0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
19ce0 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
19cf0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
19d00 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
19d10 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
19d20 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
19d30 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
19d40 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
19d50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19d60 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
19d70 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
19d80 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
19d90 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
19da0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
19db0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
19dc0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
19dd0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
19de0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
19df0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
19e00 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
19e10 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
19e20 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
19e30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
19e40 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
19e50 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
19e60 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
19e70 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
19e80 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
19e90 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
19ea0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
19eb0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
19ec0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
19ed0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
19ee0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
19ef0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
19f00 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
19f10 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
19f20 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
19f30 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
19f40 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
19f50 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
19f60 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
19f70 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
19f80 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
19f90 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
19fa0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
19fb0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
19fc0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
19fd0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
19fe0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
19ff0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
1a000 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
1a010 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
1a020 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
1a030 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1a040 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
1a050 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
1a060 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
1a070 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
1a080 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
1a090 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1a0a0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
1a0b0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
1a0c0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
1a0d0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
1a0e0 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
1a0f0 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
1a100 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
1a110 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
1a120 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
1a130 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
1a140 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
1a150 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
1a160 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1a170 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
1a180 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1a190 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
1a1a0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
1a1b0 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
1a1c0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1a1d0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1a1e0 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1a1f0 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1a200 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1a210 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1a220 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1a230 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
1a240 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1a250 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1a260 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1a270 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1a280 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1a290 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1a2a0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1a2b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a2c0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1a2d0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1a2e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1a2f0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1a300 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1a310 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1a320 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1a330 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1a340 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1a350 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1a360 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1a370 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1a380 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1a390 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1a3a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1a3b0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1a3c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1a3d0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1a3e0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1a3f0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1a400 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1a410 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1a420 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1a430 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1a440 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1a450 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1a460 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1a470 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1a480 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1a490 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1a4a0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1a4b0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1a4c0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1a4d0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1a4e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1a4f0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1a500 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1a510 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1a520 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1a530 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1a540 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1a550 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1a560 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1a570 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1a580 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1a590 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1a5a0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1a5b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1a5c0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1a5d0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1a5e0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1a5f0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1a600 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1a610 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1a620 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1a630 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1a640 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1a650 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1a660 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1a670 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1a680 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1a690 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1a6a0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1a6b0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1a6c0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1a6d0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1a6e0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1a6f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1a700 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1a710 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a720 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1a730 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1a740 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1a750 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1a760 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1a770 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1a780 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1a790 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1a7a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1a7b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a7c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a7d0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1a7e0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1a7f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a800 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1a810 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1a820 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1a830 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1a840 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1a850 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1a860 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1a870 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1a880 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1a890 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1a8a0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1a8b0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1a8c0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1a8d0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1a8e0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1a8f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a900 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1a910 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1a920 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1a930 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1a940 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1a950 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1a960 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1a970 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1a980 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a990 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1a9a0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1a9b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a9c0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1a9d0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1a9e0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1a9f0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1aa00 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1aa10 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1aa20 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1aa30 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1aa40 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1aa50 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1aa60 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1aa70 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1aa80 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1aa90 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1aaa0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1aab0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1aac0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1aad0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1aae0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1aaf0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1ab00 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1ab10 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1ab20 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1ab30 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1ab40 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1ab50 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1ab60 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1ab70 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1ab80 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1ab90 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1aba0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1abb0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1abc0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1abd0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1abe0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1abf0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1ac00 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1ac10 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1ac20 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1ac30 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1ac40 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1ac50 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1ac60 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1ac70 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1ac80 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1ac90 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1aca0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1acb0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1acc0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1acd0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1ace0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1acf0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1ad00 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1ad10 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1ad20 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1ad30 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1ad40 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1ad50 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1ad60 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1ad70 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1ad80 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1ad90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1ada0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1adb0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1adc0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1add0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1ade0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1adf0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1ae00 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1ae10 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1ae20 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1ae30 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1ae40 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1ae50 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1ae60 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1ae70 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1ae80 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1ae90 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1aea0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1aeb0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1aec0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1aed0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1aee0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1aef0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1af00 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1af10 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1af20 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1af30 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1af40 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1af50 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1af60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1af70 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1af80 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1af90 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1afa0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1afb0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1afc0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1afd0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1afe0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1aff0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1b000 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1b010 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1b020 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1b030 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b040 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1b050 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1b060 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1b070 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b080 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1b090 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1b0a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1b0b0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1b0c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b0d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1b0e0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1b0f0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1b100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1b110 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1b120 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1b130 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1b140 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1b150 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b160 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1b170 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1b180 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1b190 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1b1a0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1b1b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b1c0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1b1d0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1b1e0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1b1f0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1b200 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1b210 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1b220 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1b230 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1b240 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1b250 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1b260 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1b270 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b280 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1b290 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1b2a0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1b2b0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1b2c0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1b2d0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1b2e0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1b2f0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1b300 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1b310 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1b320 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1b330 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1b340 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1b350 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1b360 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1b370 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1b380 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1b390 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1b3a0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1b3b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1b3c0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1b3d0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1b3e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1b3f0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1b400 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1b410 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1b420 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1b430 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1b440 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1b450 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1b460 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1b470 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1b480 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1b490 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1b4a0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1b4b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1b4c0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1b4d0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1b4e0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1b4f0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1b500 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1b510 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1b520 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1b530 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1b540 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1b550 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1b560 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1b570 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1b580 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1b590 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1b5a0 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1b5b0 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1b5c0 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1b5d0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1b5e0 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1b5f0 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1b600 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1b610 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1b620 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1b630 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1b640 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1b650 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1b660 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1b670 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1b680 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1b690 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1b6a0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1b6b0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1b6c0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1b6d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1b6e0 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1b6f0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1b700 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1b710 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1b720 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1b730 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1b740 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1b750 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1b760 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1b770 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1b780 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1b790 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1b7a0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1b7b0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1b7c0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1b7d0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1b7e0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1b7f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b800 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1b810 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1b820 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1b830 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1b840 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1b850 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1b860 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1b870 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1b880 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1b890 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1b8a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1b8b0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1b8c0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1b8d0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1b8e0 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1b8f0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1b900 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1b910 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1b920 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1b930 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1b940 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1b950 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1b960 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1b970 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1b980 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1b990 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1b9a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b9b0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1b9c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1b9d0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1b9e0 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1b9f0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1ba00 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1ba10 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1ba20 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1ba30 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1ba40 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1ba50 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1ba60 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1ba70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ba80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1ba90 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1baa0 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1bab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1bac0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1bad0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1bae0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1baf0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1bb00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1bb10 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1bb20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1bb30 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1bb40 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1bb50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1bb60 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1bb70 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1bb80 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1bb90 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1bba0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1bbb0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1bbc0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1bbd0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1bbe0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1bbf0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1bc00 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1bc10 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1bc20 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1bc30 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1bc40 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1bc50 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1bc60 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1bc70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1bc80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1bc90 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1bca0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1bcb0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1bcc0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1bcd0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1bce0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1bcf0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1bd00 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1bd10 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1bd20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1bd30 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1bd40 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1bd50 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bd60 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1bd70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bd80 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1bd90 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1bda0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1bdb0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1bdc0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1bdd0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1bde0 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1bdf0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1be00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1be10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1be20 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1be30 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1be40 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1be50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1be60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1be70 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1be80 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1be90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1bea0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1beb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bec0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1bed0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1bee0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1bef0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1bf00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bf10 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1bf20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1bf30 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1bf40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1bf50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bf60 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1bf70 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1bf80 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1bf90 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1bfa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1bfb0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1bfc0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1bfd0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1bfe0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1bff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1c000 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1c010 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1c020 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1c030 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1c040 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1c050 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1c060 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1c070 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1c080 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1c090 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1c0a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c0b0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1c0c0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1c0d0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1c0e0 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1c0f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1c100 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1c110 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1c120 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1c130 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1c140 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1c150 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1c160 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c170 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c180 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1c190 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1c1a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1c1b0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1c1c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c1d0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1c1e0 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1c1f0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1c200 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c210 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c220 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1c230 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1c240 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1c250 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c260 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c270 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1c280 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1c290 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1c2a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1c2b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c2c0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1c2d0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1c2e0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1c2f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c310 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1c320 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1c330 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c340 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c360 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1c370 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1c380 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1c390 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1c3a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c3b0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1c3c0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1c3d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1c3e0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1c3f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c400 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1c410 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1c420 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1c430 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1c440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1c450 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1c460 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1c470 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1c480 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1c490 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1c4a0 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1c4b0 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1c4c0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
1c4d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
1c4e0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
1c4f0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1c500 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1c510 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
1c520 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1c530 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
1c540 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
1c550 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
1c560 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
1c570 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1c580 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1c590 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1c5a0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1c5b0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1c5c0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1c5d0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1c5e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1c5f0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1c600 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1c610 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c620 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1c630 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
1c640 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1c650 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
1c660 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1c670 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
1c680 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
1c690 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
1c6a0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
1c6b0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1c6c0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
1c6d0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1c6e0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1c6f0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1c700 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1c710 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1c720 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1c730 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1c740 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1c750 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
1c760 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c770 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1c780 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1c790 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1c7a0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
1c7b0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
1c7c0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1c7d0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
1c7e0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
1c7f0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1c800 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
1c810 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
1c820 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
1c830 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1c840 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
1c850 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1c860 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
1c870 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
1c880 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
1c890 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
1c8a0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
1c8b0 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
1c8c0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
1c8d0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
1c8e0 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
1c8f0 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
1c900 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
1c910 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
1c920 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1c930 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
1c940 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
1c950 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
1c960 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
1c970 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
1c980 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
1c990 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
1c9a0 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1c9b0 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
1c9c0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
1c9d0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
1c9e0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1c9f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1ca00 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1ca10 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1ca20 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1ca30 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
1ca40 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1ca50 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
1ca60 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
1ca70 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
1ca80 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1ca90 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
1caa0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1cab0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
1cac0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
1cad0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
1cae0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1caf0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
1cb00 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1cb10 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
1cb20 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
1cb30 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
1cb40 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1cb50 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
1cb60 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1cb70 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1cb80 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
1cb90 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1cba0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
1cbb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1cbc0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
1cbd0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1cbe0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1cbf0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1cc00 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1cc10 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
1cc20 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
1cc30 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1cc40 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
1cc50 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
1cc60 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1cc70 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
1cc80 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
1cc90 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1cca0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1ccb0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1ccc0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1ccd0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1cce0 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1ccf0 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1cd00 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  k X..**.** ^Only
1cd10 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1cd20 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1cd30 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1cd40 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1cd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cd60 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1cd70 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1cd80 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1cd90 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1cda0 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1cdb0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1cdc0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1cdd0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1cde0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1cdf0 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1ce00 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1ce10 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1ce20 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1ce30 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1ce40 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ce50 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1ce60 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1ce70 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1ce80 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1ce90 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1cea0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1ceb0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1cec0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1ced0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1cee0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1cef0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1cf00 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1cf10 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1cf20 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1cf30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1cf40 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1cf50 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1cf60 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1cf70 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cf80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1cf90 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1cfa0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1cfb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cfc0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1cfd0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1cfe0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1cff0 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
1d000 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1d010 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1d020 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
1d030 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1d040 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
1d050 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
1d060 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
1d070 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1d080 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1d090 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1d0a0 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
1d0b0 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
1d0c0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
1d0d0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1d0e0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1d0f0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1d100 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1d110 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1d120 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1d130 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1d140 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1d150 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1d160 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
1d170 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d180 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
1d190 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
1d1a0 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
1d1b0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1d1c0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
1d1d0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
1d1e0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
1d1f0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1d200 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1d210 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1d220 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
1d230 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
1d240 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
1d250 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
1d260 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
1d270 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
1d280 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1d290 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
1d2a0 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
1d2b0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
1d2c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1d2d0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
1d2e0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1d2f0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1d300 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
1d310 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1d320 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1d330 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1d340 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1d350 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1d360 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1d370 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1d380 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
1d390 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
1d3a0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
1d3b0 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
1d3c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
1d3d0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
1d3e0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
1d3f0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
1d400 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
1d410 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1d420 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
1d430 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
1d440 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1d450 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
1d460 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
1d470 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
1d480 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
1d490 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
1d4a0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
1d4b0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
1d4c0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1d4d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1d4e0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
1d4f0 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
1d500 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
1d510 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
1d520 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
1d530 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1d540 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1d550 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d560 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
1d570 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
1d580 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
1d590 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
1d5a0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
1d5b0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
1d5c0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
1d5d0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
1d5e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d5f0 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
1d600 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
1d610 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
1d620 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
1d630 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1d640 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1d650 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1d660 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1d670 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d680 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
1d690 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1d6a0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1d6b0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
1d6c0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1d6d0 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
1d6e0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1d6f0 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
1d700 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
1d710 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1d720 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
1d730 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1d740 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
1d750 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
1d760 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
1d770 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
1d780 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
1d790 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d7a0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1d7b0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1d7c0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
1d7d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1d7e0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1d7f0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1d800 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
1d810 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
1d820 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
1d830 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
1d840 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
1d850 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
1d860 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
1d870 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
1d880 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
1d890 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
1d8a0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1d8b0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1d8c0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1d8d0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1d8e0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1d8f0 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1d900 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1d910 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1d920 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1d930 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1d940 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
1d950 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
1d960 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
1d970 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
1d980 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
1d990 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1d9a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1d9b0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
1d9c0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
1d9d0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
1d9e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1d9f0 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
1da00 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
1da10 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
1da20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
1da30 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
1da40 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
1da50 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
1da60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
1da70 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
1da80 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
1da90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
1daa0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1dab0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1dac0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1dad0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dae0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1daf0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1db00 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1db10 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1db20 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1db30 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1db40 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1db50 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1db60 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
1db70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1db80 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1db90 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1dba0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dbb0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1dbc0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1dbd0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1dbe0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1dbf0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1dc00 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1dc10 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1dc20 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1dc30 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
1dc40 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1dc50 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1dc60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1dc70 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
1dc80 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
1dc90 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1dca0 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
1dcb0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1dcc0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
1dcd0 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
1dce0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1dcf0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1dd00 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
1dd10 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1dd20 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1dd30 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1dd40 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
1dd50 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
1dd60 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
1dd70 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
1dd80 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
1dd90 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
1dda0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1ddb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1ddc0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1ddd0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
1dde0 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
1ddf0 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
1de00 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1de10 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
1de20 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1de30 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
1de40 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
1de50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1de60 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
1de70 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
1de80 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1de90 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
1dea0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
1deb0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
1dec0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1ded0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1dee0 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
1def0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
1df00 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1df10 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
1df20 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1df30 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1df40 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1df50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1df60 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1df70 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1df80 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1df90 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1dfa0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1dfb0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1dfc0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1dfd0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1dfe0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1dff0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1e000 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1e010 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1e020 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1e030 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1e040 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1e050 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1e060 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1e070 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1e080 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1e090 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1e0a0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
1e0b0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1e0c0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1e0d0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
1e0e0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1e0f0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
1e100 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
1e110 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
1e120 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
1e130 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
1e140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e150 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
1e160 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
1e170 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
1e180 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
1e190 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
1e1a0 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
1e1b0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
1e1c0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1e1d0 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
1e1e0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
1e1f0 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
1e200 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
1e210 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
1e220 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
1e230 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
1e240 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1e250 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
1e260 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
1e270 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
1e280 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
1e290 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1e2a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
1e2b0 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
1e2c0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
1e2d0 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
1e2e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
1e2f0 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
1e300 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1e310 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
1e320 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
1e330 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
1e340 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
1e350 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
1e360 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
1e370 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
1e380 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
1e390 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
1e3a0 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
1e3b0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
1e3c0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
1e3d0 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
1e3e0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
1e3f0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
1e400 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
1e410 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
1e420 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1e430 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
1e440 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
1e450 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
1e460 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
1e470 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
1e480 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
1e490 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
1e4a0 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
1e4b0 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
1e4c0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
1e4d0 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
1e4e0 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
1e4f0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1e500 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
1e510 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
1e520 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
1e530 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
1e540 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
1e550 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
1e560 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
1e570 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
1e580 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
1e590 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
1e5a0 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
1e5b0 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
1e5c0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
1e5d0 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
1e5e0 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
1e5f0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
1e600 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
1e610 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
1e620 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
1e630 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
1e640 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
1e650 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
1e660 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
1e670 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
1e680 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
1e690 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
1e6a0 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
1e6b0 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
1e6c0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
1e6d0 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f  ive path. .** ^O
1e6e0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
1e6f0 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
1e700 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
1e710 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
1e720 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
1e730 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a  (e.g. "C:")..**.
1e740 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
1e750 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
1e760 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
1e770 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
1e780 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
1e790 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
1e7a0 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
1e7b0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
1e7c0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
1e7d0 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
1e7e0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1e7f0 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  n]..** SQLite in
1e800 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c  terprets the fol
1e810 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65  lowing three que
1e820 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
1e830 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
1e840 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
1e850 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
1e860 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
1e870 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
1e880 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
1e890 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
1e8a0 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
1e8b0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1e8c0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
1e8d0 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
1e8e0 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
1e8f0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1e900 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
1e910 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
1e920 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
1e930 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
1e940 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
1e950 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
1e960 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
1e970 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
1e980 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
1e990 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1e9a0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
1e9b0 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
1e9c0 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
1e9d0 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
1e9e0 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
1e9f0 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
1ea00 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
1ea10 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
1ea20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
1ea30 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1ea40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1ea50 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
1ea60 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
1ea70 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
1ea80 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
1ea90 72 20 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a  r "ro", "rw" or.
1eaa0 2a 2a 20 20 20 20 20 22 72 77 63 22 2e 20 41 74  **     "rwc". At
1eab0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
1eac0 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
1ead0 76 61 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f  value is an erro
1eae0 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
1eaf0 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
1eb00 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
1eb10 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1eb20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
1eb30 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
1eb40 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
1eb50 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1eb60 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
1eb70 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
1eb80 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
1eb90 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70  ent to sqlite3_p
1eba0 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66  repare_v2(). ^If
1ebb0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
1ebc0 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
1ebd0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
1ebe0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1ebf0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
1ec00 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
1ec10 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
1ec20 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
1ec30 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1ec40 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
1ec50 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
1ec60 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
1ec70 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
1ec80 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1ec90 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
1eca0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
1ecb0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
1ecc0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
1ecd0 41 54 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ATE. ^If sqlite3
1ece0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a  _open_v2() is .*
1ecf0 2a 20 20 20 20 20 75 73 65 64 2c 20 69 74 20 69  *     used, it i
1ed00 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
1ed10 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
1ed20 72 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  r the mode param
1ed30 65 74 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a  eter that is .**
1ed40 20 20 20 20 20 6c 65 73 73 20 72 65 73 74 72 69       less restri
1ed50 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
1ed60 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1ed70 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 61 73   flags passed as
1ed80 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20   the third .**  
1ed90 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a     parameter..**
1eda0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
1edb0 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
1edc0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
1edd0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
1ede0 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
1edf0 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
1ee00 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
1ee10 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
1ee20 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1ee30 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
1ee40 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1ee50 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
1ee60 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
1ee70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
1ee80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ee90 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
1eea0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
1eeb0 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
1eec0 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
1eed0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
1eee0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
1eef0 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
1ef00 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
1ef10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1ef20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
1ef30 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
1ef40 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
1ef50 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
1ef60 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
1ef70 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
1ef80 76 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20  viour requested 
1ef90 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
1efa0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
1efb0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
1efc0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1efd0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c  CACHE flag..** <
1efe0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
1eff0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
1f000 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
1f010 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1f020 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
1f030 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
1f040 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1f050 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1f060 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
1f070 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
1f080 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
1f090 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
1f0a0 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
1f0b0 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
1f0c0 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
1f0d0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1f0e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
1f0f0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1f100 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
1f110 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
1f120 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
1f130 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
1f140 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
1f150 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
1f160 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
1f170 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
1f180 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1f190 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
1f1a0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1f1b0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
1f1c0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
1f1d0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
1f1e0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
1f1f0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
1f200 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
1f210 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
1f220 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
1f230 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
1f240 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
1f250 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
1f260 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
1f270 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
1f280 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
1f290 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
1f2a0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1f2b0 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
1f2c0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
1f2d0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1f2e0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
1f2f0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
1f300 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
1f310 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
1f320 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
1f330 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
1f340 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1f350 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
1f360 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
1f370 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
1f380 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
1f390 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
1f3a0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
1f3b0 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
1f3c0 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
1f3d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
1f3e0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1f3f0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
1f400 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
1f410 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
1f420 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
1f430 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
1f440 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
1f450 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
1f460 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
1f470 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
1f480 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
1f490 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
1f4a0 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
1f4b0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
1f4c0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1f4d0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1f4e0 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
1f4f0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
1f500 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
1f510 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1f520 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
1f530 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
1f540 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
1f550 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
1f560 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
1f570 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1f580 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
1f590 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e  ta.db?vfs=unix-n
1f5a0 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20  olock <td>.**   
1f5b0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
1f5c0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
1f5d0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
1f5e0 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
1f5f0 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72  -nolock"..** <tr
1f600 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1f610 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
1f620 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1f630 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
1f640 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
1f650 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
1f660 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
1f670 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
1f680 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
1f690 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1f6a0 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
1f6b0 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
1f6c0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
1f6d0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
1f6e0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
1f6f0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
1f700 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
1f710 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
1f720 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
1f730 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
1f740 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
1f750 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
1f760 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
1f770 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
1f780 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
1f790 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
1f7a0 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
1f7b0 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
1f7c0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
1f7d0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
1f7e0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
1f7f0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
1f800 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
1f810 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
1f820 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
1f830 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
1f840 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
1f850 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
1f860 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
1f870 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
1f880 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
1f890 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
1f8a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
1f8b0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
1f8c0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
1f8d0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
1f8e0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1f8f0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
1f900 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1f910 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f920 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
1f930 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
1f940 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
1f950 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
1f960 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
1f970 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
1f980 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
1f990 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
1f9a0 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
1f9b0 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
1f9c0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
1f9d0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1f9e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
1f9f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1fa00 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1fa10 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1fa20 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1fa30 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1fa40 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1fa50 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1fa60 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1fa70 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1fa80 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1fa90 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1faa0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1fab0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1fac0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1fad0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1fae0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1faf0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1fb00 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1fb10 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1fb20 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1fb30 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1fb40 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1fb50 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1fb60 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1fb70 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1fb80 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1fb90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1fba0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1fbb0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1fbc0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1fbd0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1fbe0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1fbf0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
1fc00 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
1fc10 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
1fc20 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
1fc30 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
1fc40 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
1fc50 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
1fc60 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
1fc70 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
1fc80 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
1fc90 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
1fca0 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
1fcb0 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
1fcc0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
1fcd0 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
1fce0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
1fcf0 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
1fd00 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
1fd10 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
1fd20 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
1fd30 64 20 6f 66 20 61 20 56 46 53 0a 2a 2a 20 69 6d  d of a VFS.** im
1fd40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  plementation and
1fd50 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
1fd60 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
1fd70 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
1fd80 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
1fd90 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
1fda0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
1fdb0 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
1fdc0 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
1fdd0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1fde0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
1fdf0 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
1fe00 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
1fe10 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
1fe20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
1fe30 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
1fe40 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
1fe50 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
1fe60 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
1fe70 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
1fe80 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
1fe90 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
1fea0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
1feb0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
1fec0 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
1fed0 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
1fee0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
1fef0 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
1ff00 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
1ff10 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
1ff20 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
1ff30 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   The value of P 
1ff40 69 73 20 74 72 75 65 20 69 66 20 69 74 20 69 73  is true if it is
1ff50 20 22 79 65 73 22 20 6f 72 20 22 74 72 75 65 22   "yes" or "true"
1ff60 20 6f 72 20 22 6f 6e 22 20 6f 72 20 0a 2a 2a 20   or "on" or .** 
1ff70 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
1ff80 72 20 61 6e 64 20 69 73 20 66 61 6c 73 65 20 6f  r and is false o
1ff90 74 68 65 72 77 69 73 65 2e 20 20 49 66 20 50 20  therwise.  If P 
1ffa0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 20 70  is not a query p
1ffb0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6f 6e 20 46  arameter.** on F
1ffc0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
1ffd0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
1ffe0 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
1fff0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
20000 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
20010 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
20020 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
20030 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
20040 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
20050 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
20060 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
20070 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
20080 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
20090 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
200a0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
200b0 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
200c0 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
200d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
200e0 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
200f0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
20100 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
20110 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
20120 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
20130 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
20140 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
20150 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
20160 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
20170 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
20180 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
20190 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
201a0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
201b0 70 65 6e 20 56 46 53 20 6d 65 74 68 6f 64 2c 0a  pen VFS method,.
201c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
201d0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
201e0 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
201f0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
20200 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63  ndesirable..*/.c
20210 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20220 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
20230 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
20240 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
20250 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
20260 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
20270 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
20280 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
20290 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
202a0 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
202b0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
202c0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
202d0 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
202e0 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
202f0 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
20300 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
20310 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
20320 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20330 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
20340 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
20350 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
20360 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
20370 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
20380 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
20390 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
203a0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
203b0 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
203c0 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
203d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
203e0 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
203f0 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
20400 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
20410 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
20420 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
20430 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
20440 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
20450 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
20460 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
20470 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
20480 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
20490 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
204a0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
204b0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
204c0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
204d0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
204e0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
204f0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
20500 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
20510 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
20520 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
20530 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
20540 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
20550 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
20560 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
20570 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
20580 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
20590 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
205a0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
205b0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
205c0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
205d0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
205e0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
205f0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
20600 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
20610 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
20620 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
20630 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
20640 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
20650 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
20660 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
20670 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
20680 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
20690 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
206a0 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  )^.**.** When th
206b0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
206c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
206d0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
206e0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
206f0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
20700 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
20710 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
20720 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
20730 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
20740 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
20750 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
20760 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
20770 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
20780 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
20790 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
207a0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
207b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
207c0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
207d0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
207e0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
207f0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
20800 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
20810 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
20820 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
20830 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
20840 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
20850 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
20860 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
20870 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
20880 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
20890 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
208a0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
208b0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
208c0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
208d0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
208e0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
208f0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
20900 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
20910 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
20920 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
20930 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
20940 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
20950 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
20960 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
20970 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
20980 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
20990 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
209a0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
209b0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
209c0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
209d0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
209e0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
209f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
20a00 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
20a10 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
20a20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
20a30 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
20a40 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
20a50 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
20a60 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
20a70 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
20a80 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
20a90 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
20aa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
20ab0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
20ac0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
20ad0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
20ae0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
20af0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
20b00 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
20b10 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
20b20 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
20b30 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
20b40 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
20b50 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
20b60 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
20b70 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
20b80 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
20b90 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
20ba0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
20bb0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
20bc0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
20bd0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
20be0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
20bf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20c00 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
20c10 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
20c20 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
20c30 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
20c40 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
20c50 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
20c60 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
20c70 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
20c80 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
20c90 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
20ca0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
20cb0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
20cc0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
20cd0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
20ce0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
20cf0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
20d00 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
20d10 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
20d20 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
20d30 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
20d40 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
20d50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20d60 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
20d70 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
20d80 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
20d90 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
20da0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
20db0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
20dc0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
20dd0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
20de0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
20df0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
20e00 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
20e10 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
20e20 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
20e30 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
20e40 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
20e50 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
20e60 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
20e70 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
20e80 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
20e90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
20ea0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
20eb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
20ec0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
20ed0 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
20ee0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
20ef0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
20f00 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
20f10 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
20f20 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
20f30 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
20f40 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
20f50 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
20f60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
20f70 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
20f80 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
20f90 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
20fa0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
20fb0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
20fc0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
20fd0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
20fe0 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
20ff0 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
21000 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
21010 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
21020 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
21030 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
21040 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
21050 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
21060 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
21070 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
21080 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
21090 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
210a0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
210b0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
210c0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
210d0 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
210e0 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
210f0 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
21100 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
21110 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
21120 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
21130 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
21140 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
21150 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
21160 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
21170 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
21180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
21190 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
211a0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
211b0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
211c0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
211d0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
211e0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
211f0 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
21200 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
21210 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
21220 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
21230 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
21240 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
21250 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
21260 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
21270 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
21280 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
21290 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
212a0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
212b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
212c0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
212d0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
212e0 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
212f0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
21300 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
21310 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
21320 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
21330 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
21340 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
21350 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
21360 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
21370 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
21380 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
21390 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
213a0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
213b0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
213c0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
213d0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
213e0 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
213f0 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
21400 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
21410 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
21420 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
21430 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
21440 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
21450 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
21460 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
21470 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
21480 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
21490 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
214a0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
214b0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
214c0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
214d0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
214e0 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
214f0 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
21500 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
21510 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
21520 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
21530 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
21540 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
21550 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
21560 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
21570 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
21580 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
21590 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
215a0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
215b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
215c0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
215d0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
215e0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
215f0 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
21600 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
21610 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
21620 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
21630 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
21640 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
21650 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
21660 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
21670 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
21680 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
21690 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
216a0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
216b0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
216c0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
216d0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
216e0 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
216f0 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
21700 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
21710 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
21720 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
21730 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
21740 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
21750 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
21760 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
21770 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
21780 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
21790 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
217a0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
217b0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
217c0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
217d0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
217e0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
217f0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
21800 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
21810 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
21820 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
21830 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
21840 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
21850 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
21860 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
21870 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
21880 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
21890 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
218a0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
218b0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
218c0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
218d0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
218e0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
218f0 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
21900 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
21910 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
21920 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
21930 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
21940 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
21950 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21960 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
21970 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
21980 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
21990 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
219a0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
219b0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
219c0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
219d0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
219e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
219f0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
21a00 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
21a10 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
21a20 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
21a30 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
21a40 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
21a50 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
21a60 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
21a70 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
21a80 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
21a90 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
21aa0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
21ab0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21ac0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
21ad0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
21ae0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
21af0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
21b00 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
21b10 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
21b20 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
21b30 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
21b40 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
21b50 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
21b60 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
21b70 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
21b80 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
21b90 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
21ba0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
21bb0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
21bc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
21bd0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
21be0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21bf0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
21c00 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
21c10 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
21c20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
21c30 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
21c40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
21c50 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
21c60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
21c70 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
21c80 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
21c90 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
21ca0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
21cb0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
21cc0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
21cd0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
21ce0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
21cf0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
21d00 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
21d10 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
21d20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
21d30 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
21d40 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
21d50 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
21d60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
21d70 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
21d80 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
21d90 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
21da0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
21db0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
21dc0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
21dd0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
21de0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
21df0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21e00 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
21e10 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
21e20 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
21e30 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
21e40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
21e50 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
21e60 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
21e70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
21e80 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
21e90 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
21ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21eb0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
21ec0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
21ed0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
21ee0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
21ef0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
21f00 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
21f10 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
21f20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
21f30 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
21f40 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
21f50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
21f60 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
21f70 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
21f80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
21f90 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
21fa0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
21fb0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
21fc0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
21fd0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
21fe0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
21ff0 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
22000 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
22010 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22020 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
22030 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
22040 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22050 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
22060 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
22070 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
22080 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
22090 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
220a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
220b0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
220c0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
220d0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
220e0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
220f0 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
22100 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
22110 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
22120 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
22130 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
22140 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
22150 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
22160 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
22170 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
22180 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
22190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
221a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
221b0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
221c0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
221d0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
221e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
221f0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
22200 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
22210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22220 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
22230 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
22240 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
22250 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
22260 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
22270 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
22280 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
22290 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
222a0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
222b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
222c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
222d0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
222e0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
222f0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
22300 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
22310 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22320 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
22330 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
22340 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
22350 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
22360 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
22370 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
22380 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
22390 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
223a0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
223b0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
223c0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
223d0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
223e0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
223f0 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
22400 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
22410 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
22420 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
22430 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
22440 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
22450 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
22460 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
22470 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
22480 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
22490 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
224a0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
224b0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
224c0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
224d0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
224e0 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
224f0 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
22500 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
22510 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
22520 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
22530 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
22540 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
22550 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
22560 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
22570 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
22580 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
22590 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
225a0 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
225b0 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
225c0 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
225d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
225e0 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
225f0 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
22600 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
22610 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
22620 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
22630 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
22640 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
22650 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
22660 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
22670 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
22680 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
22690 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
226a0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
226b0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
226c0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
226d0 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
226e0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
226f0 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
22700 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22710 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
22720 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
22730 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
22740 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
22750 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
22760 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
22770 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
22780 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
22790 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
227a0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
227b0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
227c0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
227d0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
227e0 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
227f0 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
22800 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
22810 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
22820 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
22830 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
22840 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22850 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
22860 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
22870 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
22880 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
22890 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
228a0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
228b0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
228c0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
228d0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
228e0 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
228f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
22900 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
22910 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
22920 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
22930 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22940 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
22950 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
22960 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
22970 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
22980 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
22990 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
229a0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
229b0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
229c0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
229d0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
229e0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
229f0 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
22a00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
22a10 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
22a20 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
22a30 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
22a40 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
22a50 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
22a60 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
22a70 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
22a80 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
22a90 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
22aa0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
22ab0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
22ac0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
22ad0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
22ae0 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
22af0 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
22b00 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
22b10 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
22b20 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
22b30 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
22b40 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
22b50 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
22b60 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
22b70 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
22b80 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
22b90 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
22ba0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
22bb0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
22bc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22bd0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
22be0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
22bf0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
22c00 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
22c10 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
22c20 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
22c30 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
22c40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22c50 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
22c60 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
22c70 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
22c80 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
22c90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
22ca0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
22cb0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
22cc0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
22cd0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
22ce0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
22cf0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
22d00 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
22d10 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
22d20 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
22d30 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
22d40 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
22d50 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
22d60 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
22d70 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
22d80 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
22d90 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
22da0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
22db0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
22dc0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
22dd0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
22de0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
22df0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
22e00 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
22e10 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
22e20 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
22e30 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
22e40 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
22e50 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
22e60 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
22e70 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
22e80 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
22e90 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
22ea0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
22eb0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
22ec0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
22ed0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
22ee0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
22ef0 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
22f00 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
22f10 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
22f20 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
22f30 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
22f40 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
22f50 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
22f60 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
22f70 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
22f80 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
22f90 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
22fa0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
22fb0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
22fc0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
22fd0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
22fe0 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
22ff0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
23000 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
23010 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a   the .** </li>.*
23020 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
23030 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
23040 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
23050 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
23060 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
23070 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
23080 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
23090 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
230a0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
230b0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
230c0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
230d0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
230e0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
230f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
23100 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
23110 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
23120 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
23130 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
23140 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
23150 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
23160 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
23170 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
23180 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
23190 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
231a0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
231b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
231c0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
231d0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
231e0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
231f0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
23200 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
23210 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
23220 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
23230 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
23240 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
23250 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
23260 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
23270 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
23280 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
23290 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
232a0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
232b0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
232c0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
232d0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
232e0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
232f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
23300 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
23310 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
23320 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
23330 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
23340 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
23350 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
23360 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
23370 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
23380 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
23390 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
233a0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
233b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
233c0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
233d0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
233e0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
233f0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
23400 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23410 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
23420 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
23430 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
23440 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
23450 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
23460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
23470 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
23480 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
23490 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
234a0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
234b0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
234c0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
234d0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
234e0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
234f0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
23500 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
23510 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
23520 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
23530 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
23540 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23550 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
23560 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
23570 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
23580 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
23590 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
235a0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
235b0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
235c0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
235d0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
235e0 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
235f0 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
23600 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
23610 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
23620 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
23630 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
23640 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
23650 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23660 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
23670 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
23680 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23690 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
236a0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
236b0 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
236c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
236d0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
236e0 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
236f0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
23700 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
23710 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
23720 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23730 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
23740 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
23750 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
23760 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23770 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
23780 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
23790 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
237a0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
237b0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
237c0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
237d0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
237e0 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
237f0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
23800 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
23810 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
23820 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
23830 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
23840 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
23850 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
23860 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
23870 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
23880 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
23890 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
238a0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
238b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
238c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
238d0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
238e0 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
238f0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
23900 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
23910 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
23920 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
23930 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
23940 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
23950 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
23960 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
23970 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
23980 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
23990 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
239a0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
239b0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
239c0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
239d0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
239e0 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
239f0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
23a00 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
23a10 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
23a20 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
23a30 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
23a40 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
23a50 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
23a60 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
23a70 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
23a80 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
23a90 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
23aa0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
23ab0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
23ac0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
23ad0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
23ae0 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
23af0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
23b00 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
23b10 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
23b20 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
23b30 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
23b40 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
23b50 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
23b60 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
23b70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
23b80 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
23b90 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
23ba0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
23bb0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
23bc0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
23bd0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
23be0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
23bf0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
23c00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23c10 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
23c20 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
23c30 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
23c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23c50 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
23c60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23c70 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
23c80 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
23c90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23ca0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
23cb0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
23cc0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
23cd0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
23ce0 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
23cf0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
23d00 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
23d10 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
23d20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23d30 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
23d40 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
23d50 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
23d60 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
23d70 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
23d80 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
23d90 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
23da0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
23db0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
23dc0 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
23dd0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
23de0 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
23df0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
23e00 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
23e10 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
23e20 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
23e30 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
23e40 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
23e50 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
23e60 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
23e70 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
23e80 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
23e90 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
23ea0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
23eb0 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
23ec0 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
23ed0 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
23ee0 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
23ef0 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
23f00 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
23f10 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
23f20 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
23f30 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
23f40 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
23f50 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
23f60 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
23f70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
23f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23f90 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
23fa0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
23fb0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
23fc0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23fd0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
23fe0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23ff0 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
24000 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
24010 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
24020 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
24030 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
24040 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
24050 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
24060 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
24070 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
24080 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
24090 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
240a0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
240b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
240c0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
240d0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
240e0 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
240f0 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
24100 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
24110 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24120 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
24130 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
24140 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
24150 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
24160 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
24170 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24180 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
24190 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
241a0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
241b0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
241c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
241d0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
241e0 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
241f0 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
24200 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
24210 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
24220 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
24230 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
24240 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24250 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
24260 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
24270 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
24280 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
24290 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
242a0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
242b0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
242c0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
242d0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
242e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
242f0 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
24300 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
24310 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
24320 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
24330 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
24340 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
24350 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
24360 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
24370 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
24380 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
24390 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
243a0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
243b0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
243c0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
243d0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
243e0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
243f0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
24400 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
24410 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
24420 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
24430 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
24440 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
24450 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
24460 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
24470 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
24480 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
24490 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
244a0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
244b0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
244c0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
244d0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
244e0 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
244f0 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
24500 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
24510 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
24520 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
24530 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
24540 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
24550 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
24560 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
24570 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
24580 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
24590 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
245a0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
245b0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
245c0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
245d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
245e0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
245f0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
24600 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
24610 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
24620 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
24630 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
24640 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
24650 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
24660 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24670 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
24680 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
24690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
246a0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
246b0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
246c0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
246d0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
246e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
246f0 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
24700 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
24710 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
24720 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
24730 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
24740 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
24750 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
24760 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
24770 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
24780 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
24790 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
247a0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
247b0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
247c0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
247d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
247e0 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
247f0 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
24800 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
24810 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
24820 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
24830 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
24840 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
24850 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
24860 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
24870 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
24880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
24890 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
248a0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
248b0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
248c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
248d0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
248e0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
248f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
24900 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
24910 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
24920 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
24930 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
24940 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
24950 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
24960 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
24970 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
24980 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
24990 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
249a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
249b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
249c0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
249d0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
249e0 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
249f0 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
24a00 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
24a10 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
24a20 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
24a30 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
24a40 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
24a50 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
24a60 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
24a70 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
24a80 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
24a90 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
24aa0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24ab0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
24ac0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
24ad0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
24ae0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
24af0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
24b00 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
24b10 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
24b20 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
24b30 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
24b40 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
24b50 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
24b60 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
24b70 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
24b80 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
24b90 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
24ba0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
24bb0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
24bc0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
24bd0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
24be0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
24bf0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
24c00 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
24c10 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
24c20 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
24c30 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
24c40 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
24c50 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
24c60 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
24c70 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
24c80 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
24c90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
24ca0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
24cb0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
24cc0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
24cd0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
24ce0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
24cf0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
24d00 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
24d10 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
24d20 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
24d30 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
24d40 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
24d50 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
24d60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
24d70 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
24d80 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
24d90 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
24da0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
24db0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
24dc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
24dd0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
24de0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
24df0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
24e00 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
24e10 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
24e20 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
24e30 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
24e40 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
24e50 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
24e60 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
24e70 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
24e80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
24e90 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
24ea0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
24eb0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
24ec0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
24ed0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
24ee0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
24ef0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
24f00 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
24f10 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
24f20 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
24f30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
24f40 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
24f50 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
24f60 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
24f70 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
24f80 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
24f90 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
24fa0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
24fb0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
24fc0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
24fd0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
24fe0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
24ff0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
25000 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
25010 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
25020 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
25030 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
25040 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
25050 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
25060 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
25070 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
25080 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25090 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
250a0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
250b0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
250c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
250d0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
250e0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
250f0 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ator..** If a no
25100 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
25110 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
25120 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
25130 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
25140 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
25150 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20  d_text16() then 
25160 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
25170 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
25180 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
25190 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
251a0 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
251b0 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
251c0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
251d0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
251e0 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
251f0 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
25200 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
25210 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
25220 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
25230 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
25240 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
25250 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
25260 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
25270 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
25280 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
25290 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
252a0 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
252b0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
252c0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
252d0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
252e0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
252f0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
25300 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
25310 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
25320 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
25330 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
25340 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
25350 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
25360 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
25370 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
25380 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
25390 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
253a0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
253b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
253c0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
253d0 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  he call to sqlit
253e0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a  e3_bind_blob(),.
253f0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
25400 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74  text(), or sqlit
25410 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
25420 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66   fails.  .** ^If
25430 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
25440 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
25450 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
25460 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
25470 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
25480 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
25490 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
254a0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
254b0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
254c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
254d0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
254e0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
254f0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
25500 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
25510 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
25520 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
25530 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
25540 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
25550 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
25560 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
25570 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
25580 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
25590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
255a0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
255b0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
255c0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
255d0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
255e0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
255f0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
25600 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
25610 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
25620 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
25630 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
25640 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
25650 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
25660 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
25670 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
25680 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
25690 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
256a0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
256b0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
256c0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
256d0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
256e0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
256f0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
25700 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
25710 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
25720 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
25730 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
25740 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
25750 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
25760 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
25770 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
25780 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
25790 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
257a0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
257b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
257c0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
257d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
257e0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
257f0 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
25800 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
25810 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
25820 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
25830 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
25840 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
25850 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
25860 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
25870 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
25880 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
25890 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
258a0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
258b0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
258c0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
258d0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
258e0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
258f0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
25900 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
25910 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
25920 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
25930 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
25940 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
25950 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
25960 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
25970 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
25980 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
25990 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
259a0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
259b0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
259c0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
259d0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
259e0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
259f0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
25a00 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
25a10 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
25a20 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
25a30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
25a40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25a50 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
25a60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
25a70 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
25a80 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
25a90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25aa0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
25ab0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
25ac0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
25ad0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
25ae0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
25af0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
25b00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
25b10 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
25b20 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
25b30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25b40 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
25b50 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
25b60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25b70 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
25b80 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
25b90 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
25ba0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
25bb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25bc0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
25bd0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
25be0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
25bf0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
25c00 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
25c10 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
25c20 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
25c30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
25c40 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
25c50 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
25c60 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
25c70 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
25c80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
25c90 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
25ca0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
25cb0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
25cc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
25cd0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
25ce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
25cf0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
25d00 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
25d10 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
25d20 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
25d30 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
25d40 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
25d50 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
25d60 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
25d70 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
25d80 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
25d90 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
25da0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
25db0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
25dc0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
25dd0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
25de0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
25df0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25e00 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
25e10 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
25e20 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
25e30 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
25e40 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
25e50 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
25e60 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
25e70 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
25e80 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
25e90 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
25ea0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
25eb0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
25ec0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
25ed0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
25ee0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
25ef0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
25f00 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
25f10 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
25f20 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
25f30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
25f40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25f50 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
25f60 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
25f70 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
25f80 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
25f90 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25fa0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
25fb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
25fc0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
25fd0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
25fe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25ff0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
26000 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
26010 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26020 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
26030 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
26040 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
26050 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
26060 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
26070 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
26080 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
26090 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
260a0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
260b0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
260c0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
260d0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
260e0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
260f0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
26100 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
26110 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
26120 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
26130 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
26140 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
26150 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
26160 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
26170 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
26180 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
26190 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
261a0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
261b0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
261c0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
261d0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
261e0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
261f0 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
26200 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
26210 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
26220 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
26230 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
26240 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
26250 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
26260 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
26270 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
26280 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
26290 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
262a0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
262b0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
262c0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
262d0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
262e0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
262f0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
26300 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
26310 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
26320 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
26330 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26340 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
26350 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26360 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
26370 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
26380 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
26390 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
263a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
263b0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
263c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
263d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
263e0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
263f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
26400 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
26410 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
26420 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
26430 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
26440 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
26450 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
26460 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
26470 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
26480 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
26490 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
264a0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
264b0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
264c0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
264d0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
264e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
264f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
26500 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
26510 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
26520 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
26530 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
26540 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
26550 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
26560 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
26570 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
26580 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
26590 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
265a0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
265b0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
265c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
265d0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
265e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
265f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
26600 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
26610 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26620 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
26630 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26640 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26650 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
26660 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
26670 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
26680 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
26690 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
266a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
266b0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
266c0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
266d0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
266e0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
266f0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
26700 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
26710 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
26720 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
26730 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
26740 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
26750 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
26760 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
26770 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
26780 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
26790 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
267a0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
267b0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
267c0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
267d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
267e0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
267f0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
26800 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
26810 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
26820 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
26830 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
26840 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
26850 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26860 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
26870 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
26880 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
26890 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
268a0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
268b0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
268c0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
268d0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
268e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
268f0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
26900 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26910 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
26920 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
26930 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
26940 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
26950 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
26960 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
26970 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
26980 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
26990 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
269a0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
269b0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
269c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
269d0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
269e0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
269f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
26a00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
26a10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
26a20 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
26a30 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
26a40 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
26a50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
26a60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
26a70 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
26a80 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
26a90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
26aa0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26ab0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
26ac0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
26ad0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
26ae0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
26af0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
26b00 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
26b10 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
26b20 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
26b30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
26b40 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
26b50 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
26b60 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
26b70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26b80 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
26b90 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
26ba0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
26bb0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
26bc0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
26bd0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
26be0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
26bf0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26c00 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
26c10 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
26c20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
26c30 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
26c40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26c50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
26c60 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
26c70 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
26c80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
26c90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
26ca0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
26cb0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
26cc0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
26cd0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
26ce0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
26cf0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
26d00 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
26d10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
26d20 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
26d30 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
26d40 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
26d50 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
26d60 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
26d70 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
26d80 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
26d90 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
26da0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
26db0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
26dc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
26dd0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
26de0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
26df0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
26e00 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
26e10 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
26e20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
26e30 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
26e40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26e50 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
26e60 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26e70 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
26e80 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
26e90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26ea0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
26eb0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
26ec0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
26ed0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
26ee0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
26ef0 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
26f00 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
26f10 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
26f20 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
26f30 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
26f40 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
26f50 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
26f60 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
26f70 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
26f80 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
26f90 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
26fa0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
26fb0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
26fc0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
26fd0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
26fe0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
26ff0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
27000 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
27010 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
27020 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
27030 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
27040 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
27050 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
27060 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
27070 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
27080 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
27090 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
270a0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
270b0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
270c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
270d0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
270e0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
270f0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
27100 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
27110 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
27120 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
27130 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
27140 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
27150 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
27160 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
27170 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
27180 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
27190 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
271a0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
271b0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
271c0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
271d0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
271e0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
271f0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
27200 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
27210 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
27220 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
27230 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
27240 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
27250 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
27260 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
27270 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27280 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
27290 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
272a0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
272b0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
272c0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
272d0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
272e0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
272f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
27300 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
27310 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
27320 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
27330 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
27340 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
27350 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
27360 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
27370 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
27380 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
27390 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
273a0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
273b0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
273c0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
273d0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
273e0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
273f0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
27400 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
27410 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
27420 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
27430 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
27440 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
27450 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
27460 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
27470 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
27480 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
27490 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
274a0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
274b0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
274c0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
274d0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
274e0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
274f0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
27500 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
27510 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
27520 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
27530 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
27540 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
27550 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
27560 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
27570 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
27580 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
27590 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
275a0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
275b0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
275c0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
275d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
275e0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
275f0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
27600 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
27610 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
27620 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
27630 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
27640 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
27650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
27660 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
27670 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
27680 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
27690 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
276a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
276b0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
276c0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
276d0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
276e0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
276f0 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
27700 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
27710 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
27720 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
27730 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
27740 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27750 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
27760 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
27770 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
27780 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
27790 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
277a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
277b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
277c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
277d0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
277e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
277f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
27800 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
27810 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
27820 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
27830 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27840 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
27850 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
27860 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27870 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
27880 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
27890 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
278a0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
278b0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
278c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
278d0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
278e0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
278f0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
27900 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
27910 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
27920 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
27930 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
27940 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
27950 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
27960 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
27970 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
27980 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
27990 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
279a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
279b0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
279c0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
279d0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
279e0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
279f0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
27a00 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
27a10 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
27a20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
27a30 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
27a40 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
27a50 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
27a60 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
27a70 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
27a80 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
27a90 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
27aa0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
27ab0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
27ac0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
27ad0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
27ae0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
27af0 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
27b00 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
27b10 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
27b20 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
27b30 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
27b40 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
27b50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
27b60 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
27b70 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
27b80 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
27b90 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
27ba0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
27bb0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
27bc0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
27bd0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
27be0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
27bf0 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
27c00 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
27c10 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
27c20 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
27c30 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
27c40 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
27c50 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
27c60 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
27c70 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
27c80 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
27c90 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
27ca0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
27cb0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
27cc0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
27cd0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
27ce0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
27cf0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
27d00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
27d10 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
27d20 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
27d30 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
27d40 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
27d50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
27d60 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
27d70 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
27d80 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
27d90 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
27da0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27db0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
27dc0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
27dd0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
27de0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
27df0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27e00 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
27e10 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
27e20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
27e30 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
27e40 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
27e50 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
27e60 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
27e70 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
27e80 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
27e90 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
27ea0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
27eb0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
27ec0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
27ed0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
27ee0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
27ef0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
27f00 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
27f10 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
27f20 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
27f30 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
27f40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27f50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
27f60 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
27f70 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
27f80 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
27f90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
27fa0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
27fb0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
27fc0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
27fd0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
27fe0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
27ff0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
28000 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
28010 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
28020 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
28030 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
28040 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
28050 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
28060 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
28070 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
28080 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
28090 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
280a0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
280b0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
280c0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
280d0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
280e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
280f0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
28100 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
28110 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
28120 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
28130 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
28140 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
28150 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
28160 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
28170 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
28180 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
28190 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
281a0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
281b0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
281c0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
281d0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
281e0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
281f0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
28200 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
28210 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
28220 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
28230 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
28240 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
28250 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
28260 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
28270 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
28280 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
28290 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
282a0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
282b0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
282c0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
282d0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
282e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
282f0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
28300 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
28310 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
28320 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
28330 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
28340 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
28350 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
28360 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
28370 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
28380 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
28390 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
283a0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
283b0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
283c0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
283d0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
283e0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
283f0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
28400 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
28410 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
28420 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
28430 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
28440 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
28450 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
28460 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
28470 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
28480 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
28490 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
284a0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
284b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
284c0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
284d0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
284e0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
284f0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
28500 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
28510 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
28520 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
28530 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
28540 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
28550 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
28560 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
28570 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
28580 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
28590 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
285a0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
285b0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
285c0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
285d0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
285e0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
285f0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
28600 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
28610 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
28620 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
28630 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
28640 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
28650 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
28660 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
28670 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
28680 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
28690 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
286a0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
286b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
286c0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
286d0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
286e0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
286f0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
28700 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
28710 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
28720 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
28730 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
28740 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
28750 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
28760 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
28770 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
28780 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
28790 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
287a0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
287b0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
287c0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
287d0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
287e0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
287f0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
28800 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
28810 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
28820 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
28830 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
28840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
28850 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
28860 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
28870 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
28880 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
28890 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
288a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
288b0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
288c0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
288d0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
288e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
288f0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
28900 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
28910 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
28920 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
28930 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
28940 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
28950 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
28960 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
28970 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
28980 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
28990 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
289a0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
289b0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
289c0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
289d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
289e0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
289f0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
28a00 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
28a10 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
28a20 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
28a30 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
28a40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
28a50 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
28a60 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
28a70 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
28a80 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
28a90 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
28aa0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
28ab0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
28ac0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
28ad0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
28ae0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
28af0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
28b00 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
28b10 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
28b20 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
28b30 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
28b40 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
28b50 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
28b60 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
28b70 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
28b80 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
28b90 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
28ba0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
28bb0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
28bc0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
28bd0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
28be0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
28bf0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
28c00 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
28c10 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
28c20 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
28c30 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
28c40 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
28c50 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
28c60 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
28c70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
28c80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
28c90 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
28ca0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
28cb0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
28cc0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
28cd0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
28ce0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
28cf0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
28d00 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
28d10 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
28d20 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
28d30 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
28d40 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
28d50 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
28d60 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
28d70 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
28d80 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
28d90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28da0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
28db0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
28dc0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
28dd0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
28de0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
28df0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
28e00 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
28e10 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
28e20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
28e30 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
28e40 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
28e50 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
28e60 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
28e70 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
28e80 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
28e90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28ea0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
28eb0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
28ec0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
28ed0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
28ee0 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
28ef0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
28f00 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
28f10 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
28f20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
28f30 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
28f40 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
28f50 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
28f60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28f70 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
28f80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
28f90 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
28fa0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
28fb0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
28fc0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
28fd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
28fe0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
28ff0 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
29000 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
29010 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29020 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
29030 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29040 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
29050 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
29060 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
29070 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
29080 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
29090 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
290a0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
290b0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
290c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
290d0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
290e0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
290f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29100 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
29110 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
29120 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
29130 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29140 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
29150 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
29160 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
29170 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
29180 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
29190 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
291a0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
291b0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
291c0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
291d0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
291e0 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
291f0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
29200 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29210 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
29220 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
29230 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
29240 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
29250 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
29260 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
29270 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
29280 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
29290 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
292a0 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
292b0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
292c0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
292d0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
292e0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
292f0 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
29300 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
29310 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
29320 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
29330 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
29340 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
29350 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
29360 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
29370 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
29380 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
29390 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
293a0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
293b0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
293c0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
293d0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
293e0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
293f0 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
29400 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
29410 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
29420 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
29430 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
29440 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
29450 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
29460 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
29470 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
29480 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
29490 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
294a0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
294b0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
294c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
294d0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
294e0 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
294f0 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
29500 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
29510 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
29520 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
29530 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
29540 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
29550 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
29560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29570 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
29580 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
29590 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
295a0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
295b0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
295c0 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
295d0 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74  "result set" int
295e0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  erface..**.** ^T
295f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
29600 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
29610 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
29620 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
29630 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
29640 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
29650 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
29660 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
29670 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
29680 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
29690 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
296a0 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
296b0 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
296c0 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
296d0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
296e0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
296f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
29700 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
29710 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
29720 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
29730 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
29740 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
29750 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
29760 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
29770 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
29780 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
29790 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
297a0 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
297b0 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
297c0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
297d0 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
297e0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
297f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
29800 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
29810 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
29820 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
29830 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
29840 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
29850 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
29860 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
29870 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
29880 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
29890 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
298a0 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
298b0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
298c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
298d0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
298e0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
298f0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
29900 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
29910 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
29920 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
29930 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
29940 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
29950 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
29960 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
29970 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
29980 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
29990 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
299a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
299b0 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
299c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
299d0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
299e0 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
299f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
29a00 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
29a10 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
29a20 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
29a30 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
29a40 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
29a50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29a60 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
29a70 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
29a80 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
29a90 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
29aa0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
29ab0 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
29ac0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
29ad0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
29ae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29af0 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
29b00 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
29b10 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
29b20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
29b30 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
29b40 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
29b50 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
29b60 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
29b70 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
29b80 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
29b90 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
29ba0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
29bb0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
29bc0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
29bd0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
29be0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
29bf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29c00 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
29c10 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
29c20 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
29c30 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
29c40 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
29c50 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
29c60 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
29c70 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
29c80 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
29c90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
29ca0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
29cb0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
29cc0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
29cd0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
29ce0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
29cf0 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
29d00 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
29d10 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
29d20 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
29d30 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
29d40 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
29d50 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
29d60 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
29d70 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
29d80 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29d90 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
29da0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
29db0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
29dc0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
29dd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
29de0 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
29df0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
29e00 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
29e10 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
29e20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
29e30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
29e40 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
29e50 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
29e60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29e70 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
29e80 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
29e90 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
29ea0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
29eb0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
29ec0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
29ed0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
29ee0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
29ef0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
29f00 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
29f10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
29f20 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
29f30 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
29f40 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
29f50 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
29f60 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
29f70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29f80 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
29f90 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
29fa0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
29fb0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
29fc0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
29fd0 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
29fe0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
29ff0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2a000 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2a010 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2a020 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
2a030 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2a040 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2a050 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2a060 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2a070 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2a080 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
2a090 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2a0a0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2a0b0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2a0c0 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
2a0d0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2a0e0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2a0f0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2a100 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2a110 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2a120 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2a130 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
2a140 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2a150 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
2a160 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2a170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a180 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
2a190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a1a0 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
2a1b0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
2a1c0 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
2a1d0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
2a1e0 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
2a1f0 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
2a200 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
2a210 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a220 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
2a230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a240 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
2a250 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
2a260 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
2a270 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
2a280 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2a290 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
2a2a0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2a2b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2a2c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
2a2d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
2a2e0 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
2a2f0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
2a300 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
2a310 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
2a320 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2a330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2a340 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2a350 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
2a360 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2a370 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  ** ^The object r
2a380 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2a390 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2a3a0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
2a3b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a3c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
2a3d0 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
2a3e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a3f0 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
2a400 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
2a410 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2a420 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2a430 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2a440 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
2a450 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2a460 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a470 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2a480 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a490 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
2a4a0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
2a4b0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
2a4c0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
2a4d0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2a4e0 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
2a4f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2a500 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2a510 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2a520 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
2a530 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2a540 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
2a550 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
2a560 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
2a570 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
2a580 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
2a590 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2a5a0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2a5b0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2a5c0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2a5d0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2a5e0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2a5f0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2a600 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2a610 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2a620 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2a630 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
2a640 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
2a650 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
2a660 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
2a670 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
2a680 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2a690 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2a6a0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2a6b0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
2a6c0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
2a6d0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
2a6e0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
2a6f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2a700 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
2a710 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
2a720 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
2a730 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2a740 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
2a750 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
2a760 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2a770 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2a780 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2a790 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2a7a0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2a7b0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2a7c0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2a7d0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2a7e0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2a7f0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2a800 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2a810 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2a820 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2a830 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2a840 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2a850 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2a860 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2a870 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2a880 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2a890 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2a8a0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2a8b0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2a8c0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2a8d0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2a8e0 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
2a8f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2a900 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2a910 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2a920 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2a930 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2a940 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2a950 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2a960 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
2a970 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
2a980 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
2a990 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
2a9a0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2a9b0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2a9c0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2a9d0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
2a9e0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2a9f0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2aa00 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
2aa10 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2aa20 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2aa30 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2aa40 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2aa50 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2aa60 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2aa70 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2aa80 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
2aa90 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
2aaa0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2aab0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2aac0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2aad0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2aae0 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2aaf0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2ab00 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2ab10 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2ab20 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2ab30 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2ab40 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2ab50 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2ab60 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2ab70 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2ab80 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2ab90 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2aba0 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2abb0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2abc0 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2abd0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2abe0 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2abf0 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2ac00 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2ac10 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2ac20 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2ac30 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2ac40 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2ac50 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2ac60 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2ac70 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2ac80 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2ac90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2aca0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2acb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2acc0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2acd0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2ace0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2acf0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2ad00 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2ad10 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2ad20 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2ad30 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2ad40 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2ad50 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2ad60 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2ad70 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2ad80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ad90 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2ada0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2adb0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2adc0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2add0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2ade0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2adf0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2ae00 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2ae10 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2ae20 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2ae30 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2ae40 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2ae50 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2ae60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2ae70 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2ae80 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2ae90 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2aea0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2aeb0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2aec0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2aed0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2aee0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2aef0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2af00 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2af10 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2af20 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2af30 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2af40 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2af50 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2af60 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2af70 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2af80 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2af90 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2afa0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2afb0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2afc0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2afd0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2afe0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2aff0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2b000 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2b010 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2b020 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2b030 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2b040 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2b050 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2b060 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2b070 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2b080 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2b090 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2b0a0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2b0b0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2b0c0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2b0d0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2b0e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2b0f0 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2b100 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2b110 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2b120 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2b130 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2b140 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2b150 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2b160 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2b170 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2b180 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2b190 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2b1a0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2b1b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2b1c0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2b1d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2b1e0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2b1f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b200 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2b210 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2b220 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2b230 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2b240 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2b250 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2b260 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b270 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2b280 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2b290 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2b2a0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2b2b0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2b2c0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2b2d0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2b2e0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2b2f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b300 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2b310 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b320 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2b330 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2b340 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2b350 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2b360 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2b370 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2b380 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2b390 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2b3a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2b3b0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2b3c0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2b3d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b3e0 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2b3f0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2b400 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2b410 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2b420 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2b430 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2b440 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2b450 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2b460 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2b470 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2b480 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2b490 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2b4a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b4b0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2b4c0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2b4d0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2b4e0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2b4f0 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2b500 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2b510 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2b520 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2b530 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
2b540 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2b550 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
2b560 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
2b570 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
2b580 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2b590 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
2b5a0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2b5b0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2b5c0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2b5d0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2b5e0 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2b5f0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2b600 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2b610 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2b620 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2b630 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2b640 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2b650 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2b660 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2b670 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2b680 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2b690 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2b6a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2b6b0 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
2b6c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2b6d0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2b6e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2b6f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2b700 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2b710 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2b720 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2b730 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2b740 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b750 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
2b760 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b770 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2b780 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2b790 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2b7a0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2b7b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2b7c0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2b7d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2b7e0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2b7f0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2b800 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2b810 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2b820 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
2b830 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2b840 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2b850 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b860 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2b870 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2b880 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2b890 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2b8a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2b8b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2b8c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2b8d0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2b8e0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2b8f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2b900 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2b910 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2b920 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
2b930 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b940 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2b950 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2b960 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b970 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
2b980 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2b990 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
2b9a0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
2b9b0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
2b9c0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
2b9d0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
2b9e0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
2b9f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
2ba00 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
2ba10 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
2ba20 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2ba30 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2ba40 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
2ba50 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
2ba60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2ba70 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
2ba80 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2ba90 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
2baa0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2bab0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2bac0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2bad0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2bae0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2baf0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2bb00 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2bb10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bb20 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2bb30 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2bb40 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2bb50 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2bb60 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2bb70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2bb80 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2bb90 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2bba0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2bbb0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2bbc0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2bbd0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2bbe0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2bbf0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2bc00 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2bc10 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2bc20 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2bc30 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2bc40 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2bc50 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2bc60 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2bc70 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2bc80 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2bc90 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2bca0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2bcb0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2bcc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2bcd0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2bce0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bcf0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2bd00 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2bd10 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2bd20 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2bd30 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2bd40 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2bd50 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2bd60 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2bd70 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2bd80 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2bd90 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2bda0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
2bdb0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2bdc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2bdd0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2bde0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2bdf0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2be00 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2be10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2be20 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2be30 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2be40 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2be50 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2be60 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2be70 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2be80 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2be90 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
2bea0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2beb0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2bec0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2bed0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2bee0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2bef0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2bf00 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2bf10 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2bf20 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2bf30 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2bf40 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2bf50 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2bf60 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2bf70 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2bf80 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
2bf90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bfa0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
2bfb0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2bfc0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2bfd0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2bfe0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2bff0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2c000 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2c010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c020 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2c030 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2c040 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
2c050 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2c060 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2c070 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2c080 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
2c090 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c0a0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2c0b0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
2c0c0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2c0d0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2c0e0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2c0f0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2c100 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2c110 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2c120 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
2c130 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2c140 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2c150 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2c160 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
2c170 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2c180 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2c190 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2c1a0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
2c1b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2c1c0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2c1d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c1e0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
2c1f0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
2c200 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2c210 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2c220 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
2c230 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
2c240 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
2c250 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2c260 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2c270 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2c280 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2c290 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c2a0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2c2b0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2c2c0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c2d0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
2c2e0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
2c2f0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
2c300 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
2c310 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
2c320 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
2c330 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
2c340 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
2c350 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
2c360 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
2c370 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2c380 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2c390 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
2c3a0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
2c3b0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
2c3c0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
2c3d0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
2c3e0 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
2c3f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2c400 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
2c410 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
2c420 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
2c430 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
2c440 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
2c450 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
2c460 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
2c470 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2c480 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2c490 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2c4a0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
2c4b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2c4c0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
2c4d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
2c4e0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
2c4f0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2c500 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
2c510 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
2c520 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
2c530 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c540 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2c550 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
2c560 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
2c570 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
2c580 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2c590 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2c5a0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2c5b0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2c5c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2c5d0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2c5e0 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
2c5f0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2c600 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2c610 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
2c620 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
2c630 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
2c640 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
2c650 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
2c660 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
2c670 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
2c680 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
2c690 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
2c6a0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
2c6b0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
2c6c0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
2c6d0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
2c6e0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
2c6f0 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
2c700 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
2c710 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
2c720 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
2c730 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
2c740 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2c750 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2c760 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2c770 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2c780 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
2c790 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
2c7a0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
2c7b0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2c7c0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2c7d0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2c7e0 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
2c7f0 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
2c800 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
2c810 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2c820 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2c830 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
2c840 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
2c850 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
2c860 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
2c870 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
2c880 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
2c890 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2c8a0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
2c8b0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2c8c0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2c8d0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2c8e0 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2c8f0 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2c900 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2c910 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2c920 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66  rs.  Every SQL f
2c930 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2c940 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61  tation must be a
2c950 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2c960 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2c970 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2c980 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2c990 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2c9a0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2c9b0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2c9c0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2c9d0 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63  her.  ^An applic
2c9e0 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
2c9f0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2ca00 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2ca10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ca20 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2ca30 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2ca40 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2ca50 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2ca60 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2ca70 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2ca80 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
2ca90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2caa0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2cab0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
2cac0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
2cad0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
2cae0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
2caf0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2cb00 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
2cb10 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
2cb20 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
2cb30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2cb40 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
2cb50 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
2cb60 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
2cb70 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2cb80 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2cb90 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
2cba0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
2cbb0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
2cbc0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
2cbd0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
2cbe0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2cbf0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
2cc00 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
2cc10 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
2cc20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
2cc30 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
2cc40 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
2cc50 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
2cc60 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
2cc70 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
2cc80 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
2cc90 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
2cca0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
2ccb0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2ccc0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2ccd0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
2cce0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
2ccf0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2cd00 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2cd10 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
2cd20 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
2cd30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
2cd40 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2cd50 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2cd60 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2cd70 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
2cd80 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2cd90 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2cda0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
2cdb0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
2cdc0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
2cdd0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
2cde0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
2cdf0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2ce00 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2ce10 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2ce20 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
2ce30 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
2ce40 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
2ce50 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
2ce60 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
2ce70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2ce80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ce90 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
2cea0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
2ceb0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
2cec0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2ced0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2cee0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
2cef0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
2cf00 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
2cf10 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
2cf20 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
2cf30 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
2cf40 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2cf50 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
2cf60 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
2cf70 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
2cf80 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
2cf90 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2cfa0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2cfb0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
2cfc0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
2cfd0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
2cfe0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
2cff0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
2d000 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
2d010 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
2d020 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
2d030 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
2d040 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
2d050 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
2d060 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
2d070 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2d080 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d090 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
2d0a0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2d0b0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
2d0c0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2d0d0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
2d0e0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
2d0f0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
2d100 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
2d110 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
2d120 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
2d130 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
2d140 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2d150 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
2d160 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
2d170 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d180 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
2d190 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
2d1a0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
2d1b0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
2d1c0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
2d1d0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2d1e0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
2d1f0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
2d200 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
2d210 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
2d220 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
2d230 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
2d240 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
2d250 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
2d260 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
2d270 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2d280 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
2d290 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
2d2a0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
2d2b0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
2d2c0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2d2d0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
2d2e0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
2d2f0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2d300 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2d310 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
2d320 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
2d330 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
2d340 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
2d350 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2d360 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2d370 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
2d380 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
2d390 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
2d3a0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
2d3b0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
2d3c0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
2d3d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d3e0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
2d3f0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2d400 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2d410 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
2d420 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
2d430 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2d440 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
2d450 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
2d460 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
2d470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d480 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
2d490 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
2d4a0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2d4b0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
2d4c0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2d4d0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
2d4e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d4f0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
2d500 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2d510 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2d520 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2d530 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2d540 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2d550 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2d560 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2d570 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2d580 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2d590 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d5a0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2d5b0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2d5c0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2d5d0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
2d5e0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2d5f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
2d600 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2d610 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
2d620 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2d630 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2d640 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2d650 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2d660 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2d670 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2d680 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2d690 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2d6a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2d6b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2d6c0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2d6d0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2d6e0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
2d6f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d700 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
2d710 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2d720 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2d730 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2d740 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2d750 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2d760 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2d770 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2d780 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2d790 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2d7a0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2d7b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2d7c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2d7d0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2d7e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
2d7f0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
2d800 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
2d810 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2d820 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
2d830 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
2d840 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
2d850 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
2d860 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
2d870 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
2d880 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
2d890 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
2d8a0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
2d8b0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2d8c0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
2d8d0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2d8e0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
2d8f0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2d900 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
2d910 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
2d920 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
2d930 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
2d940 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
2d950 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
2d960 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d970 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
2d980 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2d990 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
2d9a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2d9b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
2d9c0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
2d9d0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
2d9e0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
2d9f0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
2da00 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2da10 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
2da20 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
2da30 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
2da40 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2da50 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
2da60 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
2da70 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
2da80 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2da90 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
2daa0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
2dab0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
2dac0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
2dad0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
2dae0 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
2daf0 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
2db00 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
2db10 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
2db20 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
2db30 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
2db40 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
2db50 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
2db60 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
2db70 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2db80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
2db90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2dba0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2dbb0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2dbc0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
2dbd0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2dbe0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2dbf0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
2dc00 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2dc10 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
2dc20 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
2dc30 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2dc40 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
2dc50 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
2dc60 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
2dc70 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
2dc80 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
2dc90 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2dca0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2dcb0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2dcc0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2dcd0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2dce0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2dcf0 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
2dd00 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2dd10 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
2dd20 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
2dd30 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
2dd40 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
2dd50 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
2dd60 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2dd70 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
2dd80 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
2dd90 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
2dda0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
2ddb0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
2ddc0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
2ddd0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
2dde0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
2ddf0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
2de00 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
2de10 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
2de20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
2de30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2de40 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2de50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2de60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2de70 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
2de80 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
2de90 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2dea0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2deb0 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
2dec0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
2ded0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
2dee0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2def0 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
2df00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2df10 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
2df20 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
2df30 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2df40 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
2df50 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
2df60 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
2df70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2df80 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
2df90 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
2dfa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2dfb0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
2dfc0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2dfd0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
2dfe0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2dff0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e000 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
2e010 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
2e020 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
2e030 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e040 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
2e050 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
2e060 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
2e070 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
2e080 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
2e090 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
2e0a0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
2e0b0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2e0c0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
2e0d0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
2e0e0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
2e0f0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2e100 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e110 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
2e120 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
2e130 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
2e140 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
2e150 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
2e160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e170 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2e180 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
2e190 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
2e1a0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
2e1b0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
2e1c0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
2e1d0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
2e1e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e1f0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
2e200 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e210 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
2e220 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
2e230 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
2e240 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
2e250 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
2e260 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
2e270 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
2e280 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2e290 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2e2a0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
2e2b0 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
2e2c0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
2e2d0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
2e2e0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
2e2f0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
2e300 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
2e310 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
2e320 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
2e330 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
2e340 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
2e350 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
2e360 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
2e370 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
2e380 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
2e390 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
2e3a0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
2e3b0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
2e3c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2e3d0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
2e3e0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
2e3f0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
2e400 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
2e410 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
2e420 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
2e430 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
2e440 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2e450 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2e460 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2e470 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2e480 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2e490 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
2e4a0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2e4b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2e4c0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2e4d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2e4e0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
2e4f0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
2e500 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2e510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2e520 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
2e530 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
2e540 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2e550 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2e560 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e570 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
2e580 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2e590 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2e5a0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2e5b0 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
2e5c0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
2e5d0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
2e5e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
2e5f0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
2e600 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2e610 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
2e620 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2e630 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2e640 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
2e650 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2e660 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2e670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2e680 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2e690 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
2e6a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2e6b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2e6c0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2e6d0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
2e6e0 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
2e6f0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
2e700 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
2e710 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2e720 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2e730 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2e740 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2e750 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e760 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2e770 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2e780 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2e790 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
2e7a0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2e7b0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2e7c0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2e7d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2e7e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2e7f0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2e800 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2e810 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2e820 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2e830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e840 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
2e850 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
2e860 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
2e870 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
2e880 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2e890 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
2e8a0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
2e8b0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
2e8c0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
2e8d0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
2e8e0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
2e8f0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2e900 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
2e910 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2e920 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
2e930 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
2e940 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
2e950 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
2e960 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
2e970 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
2e980 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
2e990 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2e9a0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
2e9b0 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
2e9c0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2e9d0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
2e9e0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2e9f0 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
2ea00 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2ea10 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
2ea20 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
2ea30 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
2ea40 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2ea50 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
2ea60 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
2ea70 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
2ea80 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
2ea90 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
2eaa0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
2eab0 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
2eac0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2ead0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
2eae0 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
2eaf0 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
2eb00 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
2eb10 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
2eb20 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
2eb30 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
2eb40 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
2eb50 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
2eb60 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
2eb70 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
2eb80 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
2eb90 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
2eba0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
2ebb0 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
2ebc0 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
2ebd0 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
2ebe0 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
2ebf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ec00 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2ec10 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
2ec20 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2ec30 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
2ec40 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
2ec50 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
2ec60 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2ec70 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
2ec80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
2ec90 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
2eca0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
2ecb0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2ecc0 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
2ecd0 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
2ece0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
2ecf0 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
2ed00 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
2ed10 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
2ed20 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
2ed30 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
2ed40 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2ed50 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
2ed60 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2ed70 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
2ed80 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
2ed90 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
2eda0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
2edb0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
2edc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2edd0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
2ede0 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
2edf0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2ee00 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
2ee10 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
2ee20 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
2ee30 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2ee40 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2ee50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2ee60 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2ee70 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
2ee80 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
2ee90 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
2eea0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
2eeb0 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
2eec0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2eed0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
2eee0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
2eef0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
2ef00 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2ef10 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2ef20 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2ef30 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2ef40 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
2ef50 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2ef60 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2ef70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2ef80 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
2ef90 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2efa0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
2efb0 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
2efc0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
2efd0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2efe0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2eff0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f000 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2f010 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
2f020 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
2f030 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
2f040 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
2f050 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
2f060 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f070 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
2f080 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f090 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
2f0a0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
2f0b0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
2f0c0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
2f0d0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
2f0e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2f0f0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2f100 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2f110 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2f120 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
2f130 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f140 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2f150 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2f160 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2f170 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f190 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2f1a0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
2f1b0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2f1c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2f1d0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
2f1e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f1f0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2f200 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2f210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f220 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
2f230 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2f240 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2f250 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2f260 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2f270 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2f280 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2f290 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2f2a0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2f2b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2f2c0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
2f2d0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
2f2e0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2f2f0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2f300 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2f310 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
2f320 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
2f330 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2f340 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2f350 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2f360 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2f370 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2f380 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
2f390 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
2f3a0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
2f3b0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
2f3c0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
2f3d0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2f3e0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
2f3f0 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
2f400 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
2f410 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
2f420 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
2f430 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
2f440 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2f450 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2f460 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2f470 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2f480 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2f490 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2f4a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2f4b0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2f4c0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2f4d0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2f4e0 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2f4f0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2f500 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
2f510 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
2f520 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2f530 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
2f540 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
2f550 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2f560 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
2f570 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
2f580 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2f590 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
2f5a0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
2f5b0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
2f5c0 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
2f5d0 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
2f5e0 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
2f5f0 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ocation..**.** ^
2f600 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2f610 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
2f620 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2f630 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
2f640 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
2f650 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
2f660 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2f670 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
2f680 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
2f690 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
2f6a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f6b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
2f6c0 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
2f6d0 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
2f6e0 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
2f6f0 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
2f700 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
2f710 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
2f720 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
2f730 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
2f740 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
2f750 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
2f760 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
2f770 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2f780 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
2f790 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2f7a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
2f7b0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
2f7c0 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
2f7d0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
2f7e0 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
2f7f0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
2f800 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
2f810 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
2f820 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
2f830 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f840 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
2f850 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2f860 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
2f870 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
2f880 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
2f890 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
2f8a0 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
2f8b0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f  .** ^If it is no
2f8c0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
2f8d0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
2f8e0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
2f8f0 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
2f900 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2f910 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
2f920 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
2f930 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
2f940 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
2f950 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
2f960 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
2f970 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
2f980 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2f990 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
2f9a0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
2f9b0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
2f9c0 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
2f9d0 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
2f9e0 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
2f9f0 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
2fa00 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
2fa10 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54  at any time.  ^T
2fa20 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
2fa30 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
2fa40 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
2fa50 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
2fa60 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
2fa70 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
2fa80 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
2fa90 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
2faa0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
2fab0 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
2fac0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
2fad0 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
2fae0 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
2faf0 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
2fb00 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
2fb10 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
2fb20 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs].)^.**.** The
2fb30 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2fb40 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2fb50 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2fb60 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2fb70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2fb80 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
2fb90 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
2fba0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
2fbb0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
2fbc0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
2fbd0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2fbe0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2fbf0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
2fc00 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
2fc10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
2fc20 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
2fc30 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
2fc40 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
2fc50 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
2fc60 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
2fc70 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
2fc80 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
2fc90 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
2fca0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
2fcb0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2fcc0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2fcd0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
2fce0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
2fcf0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
2fd00 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
2fd10 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
2fd20 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
2fd30 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
2fd40 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
2fd50 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2fd60 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
2fd70 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
2fd80 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
2fd90 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
2fda0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
2fdb0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
2fdc0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
2fdd0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
2fde0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
2fdf0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2fe00 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
2fe10 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
2fe20 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
2fe30 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
2fe40 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
2fe50 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
2fe60 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
2fe70 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
2fe80 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
2fe90 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
2fea0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2feb0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
2fec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
2fed0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
2fee0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2fef0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
2ff00 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
2ff10 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
2ff20 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
2ff30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ff40 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
2ff50 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
2ff60 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
2ff70 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2ff80 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
2ff90 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
2ffa0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
2ffb0 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
2ffc0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2ffd0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
2ffe0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fff0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
30000 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30010 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
30020 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
30030 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
30040 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
30050 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
30060 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
30070 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
30080 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
30090 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
300a0 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
300b0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
300c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
300d0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
300e0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
300f0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
30100 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
30110 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
30120 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30130 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
30140 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30150 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
30160 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
30170 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30180 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
30190 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
301a0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
301b0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
301c0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
301d0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
301e0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
301f0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
30200 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
30210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
30220 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
30230 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
30240 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
30250 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30260 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
30270 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
30280 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
30290 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
302a0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
302b0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
302c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
302d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
302e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
302f0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
30300 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
30310 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
30320 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30330 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
30340 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
30350 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
30360 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
30370 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
30380 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30390 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
303a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
303b0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
303c0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
303d0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
303e0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
303f0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
30400 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
30410 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
30420 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
30430 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
30440 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30450 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
30460 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
30470 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
30480 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
30490 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
304a0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
304b0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
304c0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
304d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
304e0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
304f0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
30500 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
30510 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30520 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
30530 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
30540 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
30550 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
30560 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30570 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
30580 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
30590 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
305a0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
305b0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
305c0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
305d0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
305e0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
305f0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
30600 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
30610 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
30620 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30630 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
30640 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30650 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
30660 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
30670 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
30680 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
30690 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
306a0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
306b0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
306c0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
306d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
306e0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
306f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30700 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
30710 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
30720 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
30730 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
30740 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
30750 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
30760 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
30770 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
30780 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
30790 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
307a0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
307b0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
307c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
307d0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
307e0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
307f0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
30800 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
30810 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
30820 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
30830 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
30840 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
30850 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
30860 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
30870 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
30880 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
30890 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
308a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
308b0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
308c0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
308d0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
308e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
308f0 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
30900 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
30910 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
30920 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
30930 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
30940 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
30950 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
30960 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
30970 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
30980 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
30990 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
309a0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
309b0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
309c0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
309d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
309e0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
309f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
30a00 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
30a10 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
30a20 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
30a30 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30a40 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30a50 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
30a60 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
30a70 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
30a80 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
30a90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30aa0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
30ab0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
30ac0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
30ad0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
30ae0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30af0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
30b00 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
30b10 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
30b20 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
30b30 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
30b40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
30b50 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
30b60 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
30b70 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
30b80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30b90 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30ba0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
30bb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30bc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
30bd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30be0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
30bf0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
30c00 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
30c10 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30c20 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
30c30 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
30c40 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
30c50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30c60 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30c70 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
30c80 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
30c90 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
30ca0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
30cb0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
30cc0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
30cd0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
30ce0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
30cf0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
30d00 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
30d10 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
30d20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
30d30 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
30d40 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
30d50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30d60 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
30d70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
30d80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
30d90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30da0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
30db0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
30dc0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
30dd0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
30de0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
30df0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
30e00 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
30e10 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
30e20 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
30e30 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
30e40 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
30e50 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
30e60 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
30e70 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
30e80 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
30e90 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
30ea0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
30eb0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
30ec0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
30ed0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30ee0 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
30ef0 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
30f00 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
30f10 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
30f20 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
30f30 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
30f40 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
30f50 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
30f60 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
30f70 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
30f80 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
30f90 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
30fa0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
30fb0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
30fc0 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
30fd0 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
30fe0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
30ff0 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
31000 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
31010 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
31020 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
31030 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
31040 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
31050 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
31060 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
31070 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
31080 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
31090 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
310a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
310b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
310c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
310d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
310e0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
310f0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
31100 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
31110 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
31120 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
31130 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
31140 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
31150 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
31160 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
31170 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
31180 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
31190 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
311a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
311b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
311c0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
311d0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
311e0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
311f0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
31200 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
31210 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
31220 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
31230 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
31240 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
31250 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
31260 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
31270 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
31280 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
31290 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
312a0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
312b0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
312c0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
312d0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
312e0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
312f0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
31300 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31310 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
31320 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31330 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
31340 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
31350 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
31360 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
31370 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
31380 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
31390 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
313a0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
313b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
313c0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
313d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
313e0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
313f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31400 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
31410 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31420 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31430 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
31440 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
31450 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31460 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
31470 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
31480 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
31490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
314a0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
314b0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
314c0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
314d0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
314e0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
314f0 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
31500 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
31510 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
31520 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
31530 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
31540 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
31550 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
31560 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
31570 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31580 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
31590 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
315a0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
315b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
315c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
315d0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
315e0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
315f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
31600 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
31610 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
31620 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
31630 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
31640 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
31650 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
31660 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
31670 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
31680 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
31690 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
316a0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
316b0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
316c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
316d0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
316e0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
316f0 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
31700 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
31710 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31720 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
31730 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
31740 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
31750 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
31760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31770 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
31780 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31790 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
317a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
317b0 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
317c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
317d0 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
317e0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
317f0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
31800 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31810 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
31820 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
31830 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31840 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
31850 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31860 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31870 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
31880 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31890 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
318a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
318b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
318c0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
318d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
318e0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
318f0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
31900 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
31910 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
31920 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
31930 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31940 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
31950 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
31960 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
31970 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
31980 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31990 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
319a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
319b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
319c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
319d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
319e0 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
319f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
31a00 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
31a10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
31a20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31a30 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
31a40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
31a50 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
31a60 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
31a70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31a80 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
31a90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
31aa0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
31ab0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31ac0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
31ad0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
31ae0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
31af0 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
31b00 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
31b10 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
31b20 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
31b30 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
31b40 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
31b50 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
31b60 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
31b70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
31b80 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
31b90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
31ba0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
31bb0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
31bc0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
31bd0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
31be0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31bf0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
31c00 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31c10 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
31c20 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
31c30 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
31c40 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
31c50 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
31c60 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
31c70 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
31c80 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
31c90 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
31ca0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
31cb0 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
31cc0 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
31cd0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
31ce0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
31cf0 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
31d00 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
31d10 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
31d20 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
31d30 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
31d40 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
31d50 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
31d60 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
31d70 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
31d80 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
31d90 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
31da0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
31db0 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
31dc0 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
31dd0 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
31de0 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
31df0 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
31e00 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
31e10 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
31e20 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
31e30 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
31e40 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
31e50 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
31e60 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
31e70 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
31e80 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
31e90 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
31ea0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
31eb0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
31ec0 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
31ed0 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
31ee0 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
31ef0 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
31f00 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
31f10 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
31f20 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
31f30 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
31f40 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
31f50 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
31f60 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
31f70 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
31f80 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
31f90 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
31fa0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
31fb0 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
31fc0 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
31fd0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
31fe0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
31ff0 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
32000 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
32010 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
32020 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
32030 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
32040 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
32050 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
32060 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
32070 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
32080 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
32090 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
320a0 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
320b0 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
320c0 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
320d0 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
320e0 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
320f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
32100 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
32110 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
32120 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
32130 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
32140 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
32150 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
32160 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
32170 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
32180 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
32190 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
321a0 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
321b0 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
321c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
321d0 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
321e0 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
321f0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
32200 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
32210 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
32220 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
32230 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
32240 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
32250 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
32260 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
32270 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
32280 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
32290 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
322a0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
322b0 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
322c0 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
322d0 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
322e0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
322f0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
32300 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
32310 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
32320 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
32330 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
32340 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
32350 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
32360 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
32370 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
32380 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
32390 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
323a0 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
323b0 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
323c0 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
323d0 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
323e0 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
323f0 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
32400 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
32410 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
32420 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
32430 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
32440 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
32450 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
32460 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
32470 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
32480 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
32490 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
324a0 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
324b0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
324c0 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
324d0 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
324e0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
324f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
32500 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
32510 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
32520 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
32530 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
32540 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
32550 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
32560 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
32570 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
32580 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
32590 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
325a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
325b0 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
325c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
325d0 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
325e0 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
325f0 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
32600 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
32610 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
32620 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
32630 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
32640 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
32650 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
32660 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
32670 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
32680 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
32690 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
326a0 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
326b0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
326c0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
326d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
326e0 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
326f0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
32700 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
32710 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
32720 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
32730 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
32740 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32750 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
32760 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
32770 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
32780 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
32790 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
327a0 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
327b0 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
327c0 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
327d0 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
327e0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
327f0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
32800 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32810 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
32820 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
32830 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
32840 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
32850 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
32860 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
32870 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
32880 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
32890 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
328a0 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
328b0 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
328c0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
328d0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
328e0 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
328f0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
32900 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
32910 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
32920 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
32930 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
32940 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
32950 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32960 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32970 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
32980 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
32990 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
329a0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
329b0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
329c0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
329d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
329e0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
329f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32a00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32a10 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
32a20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
32a30 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
32a40 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
32a50 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
32a60 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
32a70 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
32a80 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
32a90 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
32aa0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
32ab0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32ac0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
32ad0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
32ae0 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
32af0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
32b00 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
32b10 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
32b20 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
32b30 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
32b40 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
32b50 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
32b60 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
32b70 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
32b80 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
32b90 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
32ba0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
32bb0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
32bc0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
32bd0 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
32be0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
32bf0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
32c00 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
32c10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
32c20 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
32c30 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
32c40 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
32c50 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
32c60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
32c70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
32c80 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
32c90 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
32ca0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
32cb0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
32cc0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
32cd0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
32ce0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
32cf0 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
32d00 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
32d10 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
32d20 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
32d30 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
32d40 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
32d50 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
32d60 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
32d70 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
32d80 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
32d90 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
32da0 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
32db0 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
32dc0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
32dd0 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
32de0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
32df0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
32e00 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
32e10 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
32e20 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
32e30 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
32e40 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
32e50 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
32e60 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
32e70 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
32e80 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
32e90 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
32ea0 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
32eb0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
32ec0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
32ed0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
32ee0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
32ef0 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
32f00 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
32f10 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
32f20 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
32f30 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
32f40 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
32f50 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
32f60 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
32f70 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
32f80 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
32f90 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
32fa0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
32fb0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
32fc0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
32fd0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
32fe0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
32ff0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
33000 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
33010 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
33020 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
33030 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33040 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
33050 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
33060 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
33070 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
33080 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
33090 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
330a0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
330b0 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
330c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
330d0 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
330e0 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
330f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
33100 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
33110 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
33120 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  .);..#ifdef SQLI
33130 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a  TE_HAS_CODEC./*.
33140 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
33150 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
33160 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
33170 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
33180 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
33190 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
331a0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
331b0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
331c0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
331d0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
331e0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
331f0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
33200 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
33210 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
33220 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
33230 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
33240 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
33250 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
33260 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
33270 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
33280 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
33290 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
332a0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
332b0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
332c0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
332d0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
332e0 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
332f0 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
33300 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
33310 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
33320 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
33330 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
33340 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
33350 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
33360 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
33370 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
33380 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
33390 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
333a0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
333b0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
333c0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
333d0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
333e0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
333f0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
33400 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
33410 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
33420 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
33430 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
33440 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
33450 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
33460 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
33470 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
33480 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
33490 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
334a0 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
334b0 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
334c0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
334d0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
334e0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
334f0 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
33500 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
33510 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
33520 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
33530 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
33540 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
33550 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
33560 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
33570 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
33580 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
33590 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
335a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
335b0 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
335c0 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
335d0 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
335e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
335f0 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
33600 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
33610 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
33620 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
33630 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
33640 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
33650 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
33660 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
33670 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
33680 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
33690 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
336a0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
336b0 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
336c0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
336d0 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
336e0 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
336f0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
33700 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
33710 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
33720 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
33730 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
33740 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
33750 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
33760 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
33770 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
33780 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
33790 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
337a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
337b0 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
337c0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
337d0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
337e0 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
337f0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
33800 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
33810 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
33820 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
33830 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
33840 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
33850 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
33860 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
33870 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
33880 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
33890 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
338a0 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
338b0 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
338c0 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
338d0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
338e0 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73  graphs..*/.int s
338f0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
33900 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33910 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
33920 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
33930 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
33940 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
33950 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
33960 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
33970 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
33980 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
33990 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
339a0 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
339b0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
339c0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
339d0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
339e0 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
339f0 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
33a00 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
33a10 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
33a20 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
33a30 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
33a40 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
33a50 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
33a60 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
33a70 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
33a80 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
33a90 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
33aa0 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
33ab0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
33ac0 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
33ad0 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
33ae0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
33af0 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
33b00 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
33b10 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
33b20 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
33b30 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
33b40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33b50 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
33b60 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
33b70 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
33b80 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
33b90 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
33ba0 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
33bb0 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
33bc0 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
33bd0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
33be0 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
33bf0 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
33c00 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
33c10 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
33c20 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
33c30 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
33c40 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
33c50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
33c60 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
33c70 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
33c80 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
33c90 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
33ca0 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
33cb0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
33cc0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
33cd0 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
33ce0 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
33cf0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
33d00 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
33d10 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
33d20 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
33d30 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
33d40 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
33d50 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
33d60 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
33d70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
33d80 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
33d90 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
33da0 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
33db0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
33dc0 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
33dd0 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
33de0 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
33df0 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
33e00 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
33e10 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
33e20 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
33e30 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
33e40 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
33e50 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
33e60 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
33e70 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
33e80 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
33e90 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
33ea0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
33eb0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
33ec0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
33ed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
33ee0 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
33ef0 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f  it Mode.** KEYWO
33f00 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
33f10 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68   mode}.**.** ^Th
33f20 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
33f30 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
33f40 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
33f50 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
33f60 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
33f70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33f80 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
33f90 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
33fa0 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
33fb0 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ly.  ^Autocommit
33fc0 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
33fd0 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f  efault..** ^Auto
33fe0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
33ff0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
34000 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
34010 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
34020 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
34030 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
34040 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
34050 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
34060 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
34070 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
34080 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
34090 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
340a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
340b0 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
340c0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
340d0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
340e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
340f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
34100 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
34110 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
34120 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
34130 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
34140 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
34150 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
34160 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
34170 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
34180 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
34190 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
341a0 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
341b0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
341c0 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
341d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
341e0 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
341f0 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
34200 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
34210 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
34220 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
34230 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
34240 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
34250 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
34260 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
34270 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
34280 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
34290 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
342a0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
342b0 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
342c0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
342d0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
342e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
342f0 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
34300 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
34310 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34320 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
34330 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
34340 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
34350 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74  ongs.  ^The [dat
34360 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34370 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
34380 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
34390 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
343a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
343b0 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  ion].** that was
343c0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
343d0 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
343e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
343f0 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
34400 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
34410 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
34420 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
34430 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
34440 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
34450 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
34460 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
34470 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
34480 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
34490 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20  he Filename For 
344a0 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
344b0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
344c0 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65   sqlite3_db_file
344d0 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66  name(D,N) interf
344e0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
344f0 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e  inter to a filen
34500 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ame.** associate
34510 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20  d with database 
34520 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  N of connection 
34530 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61  D.  ^The main da
34540 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68  tabase file.** h
34550 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69  as the name "mai
34560 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  n".  If there is
34570 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61 74   no attached dat
34580 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64  abase N on the d
34590 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
345a0 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64  ction D, or if d
345b0 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20 74  atabase N is a t
345c0 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d  emporary or in-m
345d0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20  emory database, 
345e0 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  then.** a NULL p
345f0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
34600 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
34610 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64  ilename returned
34620 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
34630 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74 20  n is the output 
34640 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50  of the.** xFullP
34650 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f  athname method o
34660 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49  f the [VFS].  ^I
34670 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
34680 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
34690 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75  ill be an absolu
346a0 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65  te pathname, eve
346b0 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  n if the filenam
346c0 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65  e used.** to ope
346d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  n the database o
346e0 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20  riginally was a 
346f0 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20  URI or relative 
34700 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e  pathname..*/.con
34710 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
34720 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c  _db_filename(sql
34730 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20  ite3 *db, const 
34740 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a  char *zDbName);.
34750 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34760 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
34770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34780 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
34790 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
347a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
347b0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
347c0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
347d0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
347e0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
347f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34800 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
34810 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
34820 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
34830 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
34840 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
34850 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
34860 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
34870 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
34880 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34890 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
348a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
348b0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
348c0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
348d0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
348e0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
348f0 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
34900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
34910 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
34920 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
34930 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
34940 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
34950 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
34960 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
34970 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
34980 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
34990 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
349a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
349b0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
349c0 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
349d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
349e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
349f0 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
34a00 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
34a10 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
34a20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34a30 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
34a40 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
34a50 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
34a60 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
34a70 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
34a80 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
34a90 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
34aa0 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
34ab0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
34ac0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
34ad0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
34ae0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
34af0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
34b00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34b10 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
34b20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
34b30 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
34b40 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
34b50 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
34b60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
34b70 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
34b80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
34b90 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
34ba0 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
34bb0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
34bc0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
34bd0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
34be0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
34bf0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
34c00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34c10 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
34c20 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
34c30 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
34c40 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
34c50 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
34c60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
34c70 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
34c80 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
34c90 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
34ca0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
34cb0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
34cc0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
34cd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
34ce0 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
34cf0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
34d00 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
34d10 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
34d20 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
34d30 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
34d40 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
34d50 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
34d60 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
34d70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34d80 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
34d90 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
34da0 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
34db0 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
34dc0 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61  .** The commit a
34dd0 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  nd rollback hook
34de0 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e   callbacks are n
34df0 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a  ot reentrant..**
34e00 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
34e10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
34e20 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
34e30 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
34e40 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
34e50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
34e60 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
34e70 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
34e80 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
34e90 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
34ea0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
34eb0 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
34ec0 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
34ed0 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
34ee0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
34ef0 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
34f00 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
34f10 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
34f20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
34f30 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
34f40 20 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e   that running an
34f50 79 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74  y other SQL stat
34f60 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e  ements, includin
34f70 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  g SELECT stateme
34f80 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c  nts,.** or merel
34f90 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
34fa0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
34fb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
34fc0 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66  ep()] will modif
34fd0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
34fe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
34ff0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
35000 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
35010 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
35020 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20  ** ^Registering 
35030 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
35040 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
35050 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  lback..**.** ^Wh
35060 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
35070 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
35080 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
35090 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
350a0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
350b0 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
350c0 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49  ue normally.  ^I
350d0 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  f the commit hoo
350e0 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e  k.** returns non
350f0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
35100 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76  [COMMIT] is conv
35110 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f  erted into a [RO
35120 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65  LLBACK]..** ^The
35130 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
35140 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72  s invoked on a r
35150 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73  ollback that res
35160 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d  ults from a comm
35170 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72  it.** hook retur
35180 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a  ning non-zero, j
35190 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20  ust as it would 
351a0 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65  be with any othe
351b0 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  r rollback..**.*
351c0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
351d0 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
351e0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
351f0 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
35200 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
35210 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
35220 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
35230 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
35240 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
35250 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
35260 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
35270 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
35280 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72  occur..** ^The r
35290 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
352a0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
352b0 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
352c0 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
352d0 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
352e0 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
352f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35300 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
35310 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
35320 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
35330 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
35340 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
35350 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
35360 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
35370 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
35380 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
35390 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
353a0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
353b0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
353c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
353d0 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
353e0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
353f0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
35400 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
35410 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
35420 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
35430 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
35440 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
35450 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
35460 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
35470 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
35480 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
35490 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
354a0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
354b0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
354c0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
354d0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
354e0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
354f0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  function.** for 
35500 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
35510 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
35520 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
35530 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
35540 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
35550 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
35560 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
35570 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75  en a.** row is u
35580 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
35590 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
355a0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
355b0 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ent to the callb
355c0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
355d0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
355e0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
355f0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e  3_update_hook().
35600 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
35610 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  callback argumen
35620 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
35630 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
35640 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a  LITE_DELETE],.**
35650 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
35660 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  TE], depending o
35670 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
35680 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
35690 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62  callback.** to b
356a0 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  e invoked..** ^T
356b0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
356c0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
356d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
356e0 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
356f0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
35700 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65  e and table name
35710 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
35720 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
35730 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c   ^The final call
35740 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
35750 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
35760 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e   the row..** ^In
35770 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
35780 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
35790 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65  the [rowid] afte
357a0 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  r the update tak
357b0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
357c0 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  ^(The update hoo
357d0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
357e0 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
357f0 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65  ystem tables are
35800 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e  .** modified (i.
35810 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  e. sqlite_master
35820 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
35830 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ence).)^.**.** ^
35840 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  In the current i
35850 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74  mplementation, t
35860 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
35870 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  * is not invoked
35880 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f   when duplicatio
35890 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
358a0 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e  ed because of an
358b0 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54  .** [ON CONFLICT
358c0 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52   | ON CONFLICT R
358d0 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20  EPLACE] clause. 
358e0 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64   ^Nor is the upd
358f0 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f  ate hook.** invo
35900 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72  ked when rows ar
35910 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  e deleted using 
35920 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  the [truncate op
35930 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  timization]..** 
35940 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64  The exceptions d
35950 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70  efined in this p
35960 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63  aragraph might c
35970 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
35980 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
35990 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
359a0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d  e update hook im
359b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
359c0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
359d0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
359e0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
359f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
35a00 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75  at invoked the u
35a10 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79  pdate hook.  Any
35a20 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
35a30 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
35a40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
35a50 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
35a60 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
35a70 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
35a80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
35a90 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
35aa0 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64  riggered the upd
35ab0 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74  ate hook..** Not
35ac0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
35ad0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
35ae0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
35af0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
35b00 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
35b10 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
35b20 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
35b30 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
35b40 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
35b50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
35b60 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50  pdate_hook(D,C,P
35b70 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65  ) function.** re
35b80 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75  turns the P argu
35b90 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
35ba0 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f  evious call.** o
35bb0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
35bc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35bd0 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
35be0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
35bf0 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65  l on D..**.** Se
35c00 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
35c10 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
35c20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
35c30 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
35c40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  .** interfaces..
35c50 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
35c60 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
35c70 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
35c80 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
35c90 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
35ca0 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
35cb0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
35cc0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
35cd0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
35ce0 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
35cf0 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b  Pager Cache.** K
35d00 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
35d10 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28   cache}.**.** ^(
35d20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
35d30 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
35d40 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
35d50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
35d60 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
35d70 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
35d80 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61   between [databa
35d90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20  se connection | 
35da0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20  connections].** 
35db0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
35dc0 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73  base. Sharing is
35dd0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
35de0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
35df0 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64  .** and disabled
35e00 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
35e10 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a   is false.)^.**.
35e20 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e  ** ^Cache sharin
35e30 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
35e40 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
35e50 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
35e60 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
35e70 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
35e80 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
35e90 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
35ea0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
35eb0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
35ec0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
35ed0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
35ee0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
35ef0 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73  ** ^(The cache s
35f00 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
35f10 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
35f20 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
35f30 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
35f40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
35f50 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
35f60 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
35f70 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
35f80 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
35f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35fa0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
35fb0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
35fc0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
35fd0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
35fe0 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
35ff0 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  pened.)^.**.** ^
36000 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  (This routine re
36010 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
36020 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
36030 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
36040 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63   disabled.** suc
36050 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
36060 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
36070 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
36080 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72  e.)^.**.** ^Shar
36090 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
360a0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
360b0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
360c0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
360d0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
360e0 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
360f0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
36100 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
36110 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
36120 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
36130 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  icitly..**.** Se
36140 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65  e Also:  [SQLite
36150 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f   Shared-Cache Mo
36160 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  de].*/.int sqlit
36170 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
36180 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
36190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74  .** CAPI3REF: At
361a0 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
361b0 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20  ap Memory.**.** 
361c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
361d0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
361e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
361f0 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73   to free N bytes
36200 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  .** of heap memo
36210 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
36220 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
36230 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
36240 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74  ons.** held by t
36250 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
36260 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73  ary.   Memory us
36270 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
36280 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
36290 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
362a0 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
362b0 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
362c0 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ial memory..** ^
362d0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
362e0 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
362f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
36300 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
36310 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
36320 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
36330 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
36340 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
36350 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36360 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
36370 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d  routine is a no-
36380 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72  op returning zer
36390 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  o.** if SQLite i
363a0 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77  s not compiled w
363b0 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  ith [SQLITE_ENAB
363c0 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
363d0 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  MENT]..**.** See
363e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
363f0 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  db_release_memor
36400 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  y()].*/.int sqli
36410 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
36420 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
36430 43 41 50 49 33 52 45 46 3a 20 46 72 65 65 20 4d  CAPI3REF: Free M
36440 65 6d 6f 72 79 20 55 73 65 64 20 42 79 20 41 20  emory Used By A 
36450 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
36460 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
36470 71 6c 69 74 65 33 5f 64 62 5f 73 68 72 69 6e 6b  qlite3_db_shrink
36480 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  (D) interface at
36490 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 61  tempts to free a
364a0 73 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20 6d  s much heap.** m
364b0 65 6d 6f 72 79 20 61 73 20 70 6f 73 73 69 62 6c  emory as possibl
364c0 65 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20  e from database 
364d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 55 6e  connection D. Un
364e0 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  like the.** [sql
364f0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
36500 6f 72 79 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ory()] interface
36510 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  , this interface
36520 20 69 73 20 65 66 66 65 63 74 20 65 76 65 6e 0a   is effect even.
36530 2a 2a 20 77 68 65 6e 20 74 68 65 6e 20 5b 53 51  ** when then [SQ
36540 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
36550 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 20 63  RY_MANAGEMENT] c
36560 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
36570 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74 74 65 64  on is.** omitted
36580 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
36590 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  : [sqlite3_relea
365a0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a  se_memory()].*/.
365b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  int sqlite3_db_r
365c0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73 71  elease_memory(sq
365d0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
365e0 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
365f0 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
36600 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Size.**.** ^The
36610 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
36620 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74  ap_limit64() int
36630 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f  erface sets and/
36640 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a  or queries the.*
36650 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20  * soft limit on 
36660 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
36670 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
36680 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20  ay be allocated 
36690 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53  by SQLite..** ^S
366a0 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
366b0 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72   keep heap memor
366c0 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65  y utilization be
366d0 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65 61  low the soft hea
366e0 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65  p.** limit by re
366f0 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  ducing the numbe
36700 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20  r of pages held 
36710 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68  in the page cach
36720 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d  e.** as heap mem
36730 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72 6f  ory usages appro
36740 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e  aches the limit.
36750 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65  .** ^The soft he
36760 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66  ap limit is "sof
36770 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e 20  t" because even 
36780 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74  though SQLite st
36790 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a  rives to stay.**
367a0 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74   below the limit
367b0 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64  , it will exceed
367c0 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65   the limit rathe
367d0 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a  r than generate.
367e0 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  ** an [SQLITE_NO
367f0 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20  MEM] error.  In 
36800 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
36810 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
36820 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79   .** is advisory
36830 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   only..**.** ^Th
36840 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
36850 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  rom sqlite3_soft
36860 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
36870 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  is the size of.*
36880 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  * the soft heap 
36890 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74  limit prior to t
368a0 68 65 20 63 61 6c 6c 2c 20 6f 72 20 6e 65 67 61  he call, or nega
368b0 74 69 76 65 20 69 6e 20 74 68 65 20 63 61 73 65  tive in the case
368c0 20 6f 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e   of an.** error.
368d0 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65    ^If the argume
368e0 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  nt N is negative
368f0 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e  .** then no chan
36900 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68  ge is made to th
36910 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
36920 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  t.  Hence, the c
36930 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f  urrent.** size o
36940 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  f the soft heap 
36950 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74  limit can be det
36960 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b  ermined by invok
36970 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
36980 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
36990 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74 69  () with a negati
369a0 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ve argument..**.
369b0 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  ** ^If the argum
369c0 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68  ent N is zero th
369d0 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  en the soft heap
369e0 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c   limit is disabl
369f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ed..**.** ^(The 
36a00 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
36a10 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20  is not enforced 
36a20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  in the current i
36a30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
36a40 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   if one or more 
36a50 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  of following con
36a60 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65  ditions are true
36a70 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
36a80 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65  <li> The soft he
36a90 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20  ap limit is set 
36aa0 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e  to zero..** <li>
36ab0 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   Memory accounti
36ac0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20 75  ng is disabled u
36ad0 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69  sing a combinati
36ae0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  on of the.**    
36af0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
36b00 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
36b10 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e  G_MEMSTATUS],...
36b20 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74  ) start-time opt
36b30 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
36b40 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  the [SQLITE_DEFA
36b50 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  ULT_MEMSTATUS] c
36b60 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
36b70 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61  on..** <li> An a
36b80 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20  lternative page 
36b90 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
36ba0 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65  tion is specifie
36bb0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
36bc0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
36bd0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
36be0 50 43 41 43 48 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a  PCACHE2],...)..*
36bf0 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20  * <li> The page 
36c00 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20  cache allocates 
36c10 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d  from its own mem
36c20 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65  ory pool supplie
36c30 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71  d.**      by [sq
36c40 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
36c50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
36c60 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74  ECACHE],...) rat
36c70 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
36c80 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a   from the heap..
36c90 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
36ca0 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
36cb0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
36cc0 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68  .7.3, the soft h
36cd0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66  eap limit is enf
36ce0 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c  orced.** regardl
36cf0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
36d00 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
36d10 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
36d20 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63  MANAGEMENT].** c
36d30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
36d40 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
36d50 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  With [SQLITE_ENA
36d60 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
36d70 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73  EMENT],.** the s
36d80 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
36d90 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76  s enforced on ev
36da0 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
36db0 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a  ation.  Without.
36dc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
36dd0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
36de0 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68  ENT], the soft h
36df0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c  eap limit is onl
36e00 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68  y enforced.** wh
36e10 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  en memory is all
36e20 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70 61  ocated by the pa
36e30 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74 69  ge cache.  Testi
36e40 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61 74  ng suggests that
36e50 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20   because.** the 
36e60 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74 68  page cache is th
36e70 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65  e predominate me
36e80 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c  mory user in SQL
36e90 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70  ite, most.** app
36ea0 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61  lications will a
36eb0 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65 20  chieve adequate 
36ec0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
36ed0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68  enforcement with
36ee0 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  out.** the use o
36ef0 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  f [SQLITE_ENABLE
36f00 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
36f10 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  NT]..**.** The c
36f20 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64  ircumstances und
36f30 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 20  er which SQLite 
36f40 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65  will enforce the
36f50 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
36f60 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20   may.** changes 
36f70 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
36f80 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
36f90 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
36fa0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
36fb0 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33  _limit64(sqlite3
36fc0 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a  _int64 N);../*.*
36fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
36fe0 65 63 61 74 65 64 20 53 6f 66 74 20 48 65 61 70  ecated Soft Heap
36ff0 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65   Limit Interface
37000 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
37010 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64  *.** This is a d
37020 65 70 72 65 63 61 74 65 64 20 76 65 72 73 69 6f  eprecated versio
37030 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
37040 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37050 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  t64()].** interf
37060 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ace.  This routi
37070 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  ne is provided f
37080 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
37090 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f  mpatibility.** o
370a0 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70  nly.  All new ap
370b0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
370c0 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  d use the.** [sq
370d0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
370e0 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72  limit64()] inter
370f0 66 61 63 65 20 72 61 74 68 65 72 20 74 68 61 6e  face rather than
37100 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51   this one..*/.SQ
37110 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
37120 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
37130 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
37140 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   N);.../*.** CAP
37150 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d  I3REF: Extract M
37160 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
37170 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
37180 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  e.**.** ^This ro
37190 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65  utine returns me
371a0 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  tadata about a s
371b0 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
371c0 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  f a specific.** 
371d0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
371e0 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
371f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37200 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
37210 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
37220 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
37230 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
37240 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20   ^The column is 
37250 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
37260 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
37270 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
37280 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73  eters to.** this
37290 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20   function. ^The 
372a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
372b0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
372c0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
372d0 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
372e0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20  in", "temp", or 
372f0 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
37300 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
37310 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
37320 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
37330 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c   ^If it is NULL,
37340 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
37350 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
37360 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
37370 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
37380 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
37390 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20  thm used by the 
373a0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
373b0 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  to.** resolve un
373c0 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
373d0 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
373e0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
373f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
37400 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
37410 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
37420 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e and column.** 
37430 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
37440 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
37450 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
37460 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
37470 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20  eters.** may be 
37480 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74  NULL..**.** ^Met
37490 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65  adata is returne
374a0 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
374b0 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
374c0 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74  ions passed as t
374d0 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75  he 5th.** and su
374e0 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
374f0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
37500 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68  tion. ^Any of th
37510 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  ese arguments ma
37520 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e  y be.** NULL, in
37530 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
37540 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
37550 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74  ement of metadat
37560 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  a is omitted..**
37570 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74  .** ^(<blockquot
37580 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
37590 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
375a0 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c  <th> Parameter <
375b0 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79  th> Output<br>Ty
375c0 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70  pe <th>  Descrip
375d0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  tion.**.** <tr><
375e0 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 5th <td> con
375f0 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61  st char* <td> Da
37600 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c  ta type.** <tr><
37610 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 6th <td> con
37620 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61  st char* <td> Na
37630 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f  me of default co
37640 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
37650 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68  .** <tr><td> 7th
37660 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
37670 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
37680 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20  olumn has a NOT 
37690 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a  NULL constraint.
376a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20  ** <tr><td> 8th 
376b0 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
376c0 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
376d0 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20  lumn is part of 
376e0 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a  the PRIMARY KEY.
376f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20  ** <tr><td> 9th 
37700 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
37710 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
37720 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43  lumn is [AUTOINC
37730 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62  REMENT].** </tab
37740 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
37750 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
37760 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
37770 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
37780 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
37790 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
377a0 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
377b0 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
377c0 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
377d0 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
377e0 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
377f0 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
37800 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
37810 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
37820 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
37830 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20  ally a view, an 
37840 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
37850 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
37860 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
37870 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
37880 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
37890 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a  rowid_" and an.*
378a0 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  * [INTEGER PRIMA
378b0 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68  RY KEY] column h
378c0 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
378d0 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
378e0 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
378f0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
37900 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
37910 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
37920 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72  olumn. ^(If ther
37930 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
37940 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b  citly declared [
37950 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
37960 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65  KEY] column, the
37970 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
37980 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
37990 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  et as follows:.*
379a0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
379b0 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
379c0 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
379d0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
379e0 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
379f0 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
37a00 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
37a10 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
37a20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
37a30 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
37a40 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  (This function m
37a50 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
37a60 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
37a70 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
37a80 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
37a90 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
37aa0 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
37ab0 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
37ac0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
37ad0 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
37ae0 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  nd, an [error co
37af0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
37b00 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
37b10 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20  sage left.** in 
37b20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37b30 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65  nnection] (to be
37b40 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
37b50 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
37b60 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  )).)^.**.** ^Thi
37b70 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76  s API is only av
37b80 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
37b90 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
37ba0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
37bb0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
37bc0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
37bd0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
37be0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
37bf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61  /.int sqlite3_ta
37c00 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64  ble_column_metad
37c10 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ata(.  sqlite3 *
37c20 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
37c30 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e     /* Connection
37c40 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
37c50 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
37c60 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61  ,        /* Data
37c70 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c  base name or NUL
37c80 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  L */.  const cha
37c90 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20  r *zTableName,  
37ca0 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65     /* Table name
37cb0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
37cc0 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20   *zColumnName,  
37cd0 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65    /* Column name
37ce0 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
37cf0 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20   **pzDataType,  
37d00 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63    /* OUTPUT: Dec
37d10 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20  lared data type 
37d20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
37d30 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20  **pzCollSeq,    
37d40 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c   /* OUTPUT: Coll
37d50 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e  ation sequence n
37d60 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e  ame */.  int *pN
37d70 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20  otNull,         
37d80 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
37d90 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c  True if NOT NULL
37da0 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73   constraint exis
37db0 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72  ts */.  int *pPr
37dc0 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20  imaryKey,       
37dd0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
37de0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61  rue if column pa
37df0 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e  rt of PK */.  in
37e00 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20  t *pAutoinc     
37e10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
37e20 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
37e30 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72  umn is auto-incr
37e40 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ement */.);../*.
37e50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61  ** CAPI3REF: Loa
37e60 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a  d An Extension.*
37e70 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
37e80 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51  face loads an SQ
37e90 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
37ea0 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20  ibrary from the 
37eb0 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  named file..**.*
37ec0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
37ed0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
37ee0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
37ef0 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a  ts to load an.**
37f00 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
37f10 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
37f20 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20  ned in the file 
37f30 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  zFile..**.** ^Th
37f40 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
37f50 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f   zProc..** ^zPro
37f60 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77  c may be 0, in w
37f70 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61  hich case the na
37f80 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
37f90 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74  point.** default
37fa0 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78  s to "sqlite3_ex
37fb0 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a  tension_init"..*
37fc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
37fd0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
37fe0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37ff0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  s.** [SQLITE_OK]
38000 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
38010 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
38020 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
38030 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61   wrong..** ^If a
38040 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
38050 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
38060 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
38070 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  * [sqlite3_load_
38080 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
38090 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
380a0 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20  empt to.** fill 
380b0 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65  *pzErrMsg with e
380c0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
380d0 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f  t stored in memo
380e0 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ry.** obtained f
380f0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38100 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c  loc()]. The call
38110 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
38120 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73  should free this
38130 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69   memory by calli
38140 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
38150 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  ()]..**.** ^Exte
38160 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
38170 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
38180 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
38190 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
381a0 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74  nsion()] prior t
381b0 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41  o calling this A
381c0 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  PI,.** otherwise
381d0 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
381e0 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  e returned..**.*
381f0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
38200 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
38210 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
38220 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
38230 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20  oad_extension(. 
38240 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
38250 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74         /* Load t
38260 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74  he extension int
38270 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  o this database 
38280 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20  connection */.  
38290 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
382a0 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66  e,    /* Name of
382b0 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72   the shared libr
382c0 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65  ary containing e
382d0 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f  xtension */.  co
382e0 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c  nst char *zProc,
382f0 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69      /* Entry poi
38300 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f  nt.  Derived fro
38310 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a  m zFile if 0 */.
38320 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73    char **pzErrMs
38330 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65  g       /* Put e
38340 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72  rror message her
38350 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b  e if not 0 */.);
38360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38370 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
38380 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  ble Extension Lo
38390 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20  ading.**.** ^So 
383a0 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73  as not to open s
383b0 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e  ecurity holes in
383c0 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69   older applicati
383d0 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ons that are.** 
383e0 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65  unprepared to de
383f0 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f  al with extensio
38400 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61  n loading, and a
38410 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73  s a means of dis
38420 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73  abling.** extens
38430 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c  ion loading whil
38440 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65  e evaluating use
38450 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74  r-entered SQL, t
38460 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49  he following API
38470 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20  .** is provided 
38480 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c  to turn the [sql
38490 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
384a0 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d  ion()] mechanism
384b0 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a   on and off..**.
384c0 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  ** ^Extension lo
384d0 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20  ading is off by 
384e0 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63  default. See tic
384f0 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43  ket #1863..** ^C
38500 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  all the sqlite3_
38510 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
38520 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20  nsion() routine 
38530 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a  with onoff==1.**
38540 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
38550 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e  on loading on an
38560 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
38570 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a  noff==0 to turn.
38580 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  ** it back off a
38590 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gain..*/.int sql
385a0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
385b0 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74  _extension(sqlit
385c0 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66  e3 *db, int onof
385d0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
385e0 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c  REF: Automatical
385f0 6c 79 20 4c 6f 61 64 20 53 74 61 74 69 63 61 6c  ly Load Statical
38600 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73  ly Linked Extens
38610 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
38620 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
38630 73 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  s the xEntryPoin
38640 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  t() function to 
38650 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a  be invoked for.*
38660 2a 20 65 61 63 68 20 6e 65 77 20 5b 64 61 74 61  * each new [data
38670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38680 20 74 68 61 74 20 69 73 20 63 72 65 61 74 65 64   that is created
38690 2e 20 20 54 68 65 20 69 64 65 61 20 68 65 72 65  .  The idea here
386a0 20 69 73 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74   is that.** xEnt
386b0 72 79 50 6f 69 6e 74 28 29 20 69 73 20 74 68 65  ryPoint() is the
386c0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 66 6f 72   entry point for
386d0 20 61 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69   a statically li
386e0 6e 6b 65 64 20 53 51 4c 69 74 65 20 65 78 74 65  nked SQLite exte
386f0 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  nsion.** that is
38700 20 74 6f 20 62 65 20 61 75 74 6f 6d 61 74 69 63   to be automatic
38710 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f  ally loaded into
38720 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73   all new databas
38730 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a  e connections..*
38740 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75  *.** ^(Even thou
38750 67 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  gh the function 
38760 70 72 6f 74 6f 74 79 70 65 20 73 68 6f 77 73 20  prototype shows 
38770 74 68 61 74 20 78 45 6e 74 72 79 50 6f 69 6e 74  that xEntryPoint
38780 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61  () takes.** no a
38790 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 72 65 74  rguments and ret
387a0 75 72 6e 73 20 76 6f 69 64 2c 20 53 51 4c 69 74  urns void, SQLit
387b0 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79  e invokes xEntry
387c0 50 6f 69 6e 74 28 29 20 77 69 74 68 20 74 68 72  Point() with thr
387d0 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  ee.** arguments 
387e0 61 6e 64 20 65 78 70 65 63 74 73 20 61 6e 64 20  and expects and 
387f0 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 61  integer result a
38800 73 20 69 66 20 74 68 65 20 73 69 67 6e 61 74 75  s if the signatu
38810 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74  re of the.** ent
38820 72 79 20 70 6f 69 6e 74 20 77 68 65 72 65 20 61  ry point where a
38830 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
38840 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70