/ Hex Artifact Content
Login

Artifact c8b27ba43bb35a26b6067b8f24f06c24af2d1b64:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5600: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5610: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
5620: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
5640: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
5650: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5660: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
5680: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
5690: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
56a0: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
56b0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
56c0: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
56d0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
56e0: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5700: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5720: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
5730: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5740: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
5750: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5760: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
5770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5780: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5790: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
57a0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
57d0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
57e0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5810: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5820: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5850: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
5860: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5870: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5880: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
5890: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
58a0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
58b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
58c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58d0: 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53  _CHECK        (S
58e0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58f0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5910: 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20  AINT_COMMITHOOK 
5920: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5930: 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  AINT | (2<<8)).#
5940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5950: 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e  NSTRAINT_FOREIGN
5960: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5970: 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38  NSTRAINT | (3<<8
5980: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5990: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e  E_CONSTRAINT_FUN
59a0: 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54  CTION     (SQLIT
59b0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
59c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
59d0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59e0: 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53  _NOTNULL      (S
59f0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5a00: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5a20: 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20  AINT_PRIMARYKEY 
5a30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a40: 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23  AINT | (6<<8)).#
5a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a60: 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52  NSTRAINT_TRIGGER
5a70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38  NSTRAINT | (7<<8
5a90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5aa0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49  E_CONSTRAINT_UNI
5ab0: 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54  QUE       (SQLIT
5ac0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ad0: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5ae0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5af0: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53  _VTAB         (S
5b00: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b10: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5b20: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
5b30: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
5b40: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
5b50: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5b60: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
5b70: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
5b80: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
5b90: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5ba0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
5bb0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
5bc0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
5bd0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  G | (1<<8))../*.
5be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5bf0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5c00: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5c10: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5c20: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5c30: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5c40: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5c50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5c60: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5c70: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5c80: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5c90: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5ca0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5cb0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5cc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5cd0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5ce0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5cf0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5d00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5d10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5d20: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5d30: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5d40: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5d50: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5d60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5d70: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5d80: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5d90: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5da0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5db0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5dc0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5dd0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5de0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5e00: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5e10: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5e20: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5e40: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5e50: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5e60: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5e80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5e90: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5ea0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5eb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ec0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
5ed0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
5ee0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
5ef0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5f10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5f20: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5f30: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
5f40: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5f60: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5f70: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
5f80: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
5fa0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
5fb0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
5fc0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5fd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5fe0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
5ff0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6000: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6010: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6020: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6030: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6040: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6050: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6060: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
6070: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
6080: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6090: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
60a0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
60b0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
60c0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
60e0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
60f0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6100: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6110: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6120: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6130: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6140: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6150: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6160: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6170: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
6180: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
6190: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
61a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
61b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
61d0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
61e0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
61f0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6200: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6220: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6230: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6240: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6250: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6260: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6270: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6280: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6290: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
62a0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
62b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
62c0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
62d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
62e0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
62f0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6300: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6310: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6320: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6330: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6340: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6350: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6360: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6370: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6380: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6390: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
63a0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
63b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
63c0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
63d0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
63e0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
63f0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6400: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6410: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6420: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6430: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6440: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6450: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6460: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6470: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6480: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6490: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
64a0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
64b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
64c0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
64d0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
64e0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
64f0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6500: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6510: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6520: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6530: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6540: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6550: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6560: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6570: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6580: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6590: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
65a0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
65b0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
65c0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
65d0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
65e0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
65f0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6600: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6610: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6620: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6630: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6640: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6650: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6660: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6670: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6680: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6690: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
66a0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
66b0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
66c0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
66d0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
66e0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
66f0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6700: 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a  e unchanged..*/.
6710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6720: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6730: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6740: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6750: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6760: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6770: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6790: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
67a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
67b0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
67c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
67d0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
67e0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
67f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6800: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
6810: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6820: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
6830: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6850: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
6860: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6870: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
6880: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
68a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
68b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
68c0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
68d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68e0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
68f0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
6900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6910: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6920: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6930: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
6940: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6950: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
6960: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
6970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6980: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
6990: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
69a0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
69b0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
69c0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
69d0: 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a  0x00001000../*.*
69e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
69f0: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
6a00: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
6a10: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
6a20: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6a30: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
6a40: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6a50: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
6a60: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6a70: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
6a80: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
6a90: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6aa0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
6ab0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6ac0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
6ad0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6ae0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
6af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6b00: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
6b10: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
6b20: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
6b30: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
6b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6b50: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
6b60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
6b70: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
6b80: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
6b90: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
6ba0: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
6bb0: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
6bc0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6bd0: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
6be0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
6bf0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
6c00: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6c10: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
6c20: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
6c30: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6c40: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
6c50: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
6c60: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
6c70: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
6c80: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
6c90: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
6ca0: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
6cb0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
6cc0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
6cd0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6ce0: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
6cf0: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
6d00: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
6d10: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
6d20: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
6d30: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
6d40: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6d50: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
6d60: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6d70: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6d80: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6d90: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6da0: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
6db0: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
6dc0: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
6dd0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6de0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
6df0: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
6e00: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6e10: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
6e20: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6e30: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
6e40: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
6e50: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
6e60: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
6e70: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
6e80: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
6e90: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
6ea0: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
6eb0: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
6ec0: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
6ed0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6ee0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6ef0: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
6f00: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
6f10: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
6f20: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
6f30: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
6f40: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
6f50: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
6f60: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
6f70: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
6f80: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
6f90: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
6fa0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
6fb0: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
6fc0: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
6fd0: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
6fe0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6ff0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7000: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
7010: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
7020: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
7030: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
7040: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
7050: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
7060: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
7070: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7080: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
7090: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
70a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
70b0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
70c0: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
70d0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
70e0: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
70f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7100: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7110: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
7120: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
7130: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
7140: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
7150: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
7160: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
7170: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
7180: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
7190: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
71a0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
71b0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
71c0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
71d0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
71e0: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
71f0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
7200: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7210: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
7220: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
7230: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
7240: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7250: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
7260: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
7270: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
7280: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
7290: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
72a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
72b0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
72c0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
72d0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
72e0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
72f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
7300: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7310: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
7320: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
7330: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7340: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
7350: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
7360: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
7370: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
7380: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
7390: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
73a0: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
73b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
73c0: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
73d0: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
73e0: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
73f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7400: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7410: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7420: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
7430: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
7440: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
7450: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
7460: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
7470: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
7480: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
7490: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
74a0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
74b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
74c0: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
74d0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
74e0: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
74f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7500: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7510: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7520: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7530: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7540: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
7550: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
7560: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
7570: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7580: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
7590: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
75a0: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
75b0: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
75c0: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
75d0: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
75e0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
75f0: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7600: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7610: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7620: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7630: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
7640: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
7650: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7660: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
7670: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
7680: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
7690: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
76a0: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
76b0: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
76c0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
76d0: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
76e0: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
76f0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7700: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7710: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7720: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7730: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
7740: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
7750: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
7760: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
7770: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
7780: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
7790: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
77a0: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
77b0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
77c0: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
77d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
77e0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
77f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7800: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
7810: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
7820: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
7830: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7840: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
7850: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7860: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
7870: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
7880: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
7890: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
78a0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
78b0: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
78c0: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
78d0: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
78e0: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
78f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
7900: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
7910: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
7920: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
7930: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
7940: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7950: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
7960: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
7970: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
7980: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
7990: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
79a0: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
79b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
79c0: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
79d0: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
79e0: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
79f0: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
7a00: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7a10: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
7a20: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
7a30: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
7a40: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7a50: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
7a60: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
7a70: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
7a80: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
7a90: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
7aa0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
7ab0: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
7ac0: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
7ad0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
7ae0: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
7af0: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
7b00: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
7b10: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
7b20: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
7b30: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
7b40: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7b50: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
7b60: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
7b70: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
7b80: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
7b90: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
7ba0: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
7bb0: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
7bc0: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
7bd0: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
7be0: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
7bf0: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
7c00: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
7c10: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
7c20: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
7c30: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
7c40: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
7c50: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
7c60: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ** A [SQLITE_FCN
7c70: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c  TL_LOCKSTATE | l
7c80: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
7c90: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
7ca0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
7cb0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
7cc0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
7cd0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7ce0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
7cf0: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
7d00: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
7d10: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
7d20: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7d30: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
7d40: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
7d50: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
7d60: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7d70: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
7d80: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
7d90: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
7da0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
7db0: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
7dc0: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
7dd0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
7de0: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
7df0: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
7e00: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
7e10: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
7e20: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
7e30: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
7e40: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
7e50: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
7e60: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
7e70: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
7e80: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7e90: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
7ea0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
7eb0: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
7ec0: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
7ed0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7ee0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7ef0: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
7f00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7f10: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
7f20: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f30: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
7f40: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f50: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
7f60: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f70: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
7f80: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f90: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
7fa0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7fb0: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
7fc0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7fd0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
7fe0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7ff0: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8000: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8010: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8020: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8030: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8040: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
8050: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8060: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
8070: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
8080: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
8090: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
80a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
80b0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
80c0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
80d0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
80e0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
80f0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8100: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8110: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8120: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8130: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8140: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
8150: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8160: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
8170: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
8180: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
8190: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
81a0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
81b0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
81c0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
81d0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
81e0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
81f0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8200: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8210: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8220: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8230: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8240: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8250: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
8260: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
8270: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
8280: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8290: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
82a0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
82b0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
82c0: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
82d0: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
82e0: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
82f0: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8300: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8310: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8320: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8330: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8340: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8350: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
8360: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
8370: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
8380: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8390: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
83a0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
83b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
83c0: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
83d0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
83e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
83f0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8400: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8410: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8420: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8430: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8440: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8450: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8460: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8470: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
8480: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8490: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
84a0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
84b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
84c0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
84d0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
84e0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
84f0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8500: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8510: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8520: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8530: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8540: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8550: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8560: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8570: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8580: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8590: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
85a0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
85b0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
85c0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
85d0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
85e0: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
85f0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
8600: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8610: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8620: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8630: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8640: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8660: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8670: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8680: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
8690: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
86a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
86b0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
86c0: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
86d0: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
86e0: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
86f0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
8700: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8710: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8720: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8730: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8740: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8750: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8760: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8770: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8780: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8790: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
87a0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
87b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
87c0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
87d0: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
87e0: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
87f0: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
8800: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8810: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8820: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8830: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8840: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8850: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
8860: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
8870: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
8880: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
8890: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
88a0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
88b0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
88c0: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  des.**.** These 
88d0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
88e0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
88f0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8900: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8910: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8920: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8930: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8940: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8950: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
8960: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
8970: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
8980: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
8990: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
89a0: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
89b0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
89c0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
89d0: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
89e0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
89f0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
8a00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
8a10: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
8a20: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
8a30: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
8a40: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
8a50: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
8a60: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
8a70: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
8a80: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
8a90: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
8aa0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
8ab0: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
8ac0: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
8ad0: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
8ae0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
8af0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
8b00: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69  SQLITE_TEST.** i
8b10: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75  s defined..** <u
8b20: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
8b30: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8b40: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NT]].** The [SQL
8b50: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8b60: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
8b70: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
8b80: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
8b90: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
8ba0: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
8bb0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
8bc0: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
8bd0: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
8be0: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
8bf0: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
8c00: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
8c10: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
8c20: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
8c30: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
8c40: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
8c50: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
8c60: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
8c70: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
8c80: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
8c90: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
8ca0: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
8cb0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8cc0: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a  run faster..**.*
8cd0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8ce0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8cf0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d00: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8d10: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8d20: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
8d30: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
8d40: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
8d50: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
8d60: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
8d70: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
8d80: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
8d90: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
8da0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
8db0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8dc0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
8dd0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
8de0: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
8df0: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
8e00: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
8e10: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
8e20: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
8e30: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
8e40: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
8e50: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
8e60: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
8e70: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
8e80: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
8e90: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
8ea0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
8eb0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
8ec0: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c  systems..**.** <
8ed0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8ee0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d  L_FILE_POINTER]]
8ef0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8f00: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8f10: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
8f20: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
8f30: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
8f40: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
8f50: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
8f60: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
8f70: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
8f80: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
8f90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8fa0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f  le_control()] do
8fb0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  cumentation for.
8fc0: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
8fd0: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
8fe0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8ff0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9000: 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  ]].** ^(The [SQL
9010: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
9020: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69  MITTED] opcode i
9030: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9040: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c  rnally by.** SQL
9050: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  ite and sent to 
9060: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61  all VFSes in pla
9070: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20  ce of a call to 
9080: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9090: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74  .** when the dat
90a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
90b0: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e   has [PRAGMA syn
90c0: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f  chronous] set to
90d0: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20   OFF.)^.** Some 
90e0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
90f0: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  s need this sign
9100: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f  al in order to o
9110: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79  perate correctly
9120: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41  .** when [PRAGMA
9130: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
9140: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9150: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62  s=OFF] is set, b
9160: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65  ut most .** VFSe
9170: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  s do not need th
9180: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68  is signal and sh
9190: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
91a0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
91b0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
91c0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
91d0: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
91e0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
91f0: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  this.** opcode a
9200: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9210: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9220: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9230: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a  ialized VFSes.**
9240: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9250: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9260: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9270: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
9280: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9290: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
92a0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
92b0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
92c0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
92d0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
92e0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
92f0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9300: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9310: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9320: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9330: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9340: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
9350: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
9360: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
9370: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
9380: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
9390: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
93a0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
93b0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
93c0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
93d0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
93e0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
93f0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9400: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9410: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9420: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9430: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9440: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
9450: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
9460: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
9470: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
9480: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
9490: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
94a0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
94b0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
94c0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
94d0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
94e0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
94f0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9500: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9510: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9520: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9530: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9540: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
9550: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
9560: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
9570: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
9580: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
9590: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
95a0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
95b0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
95c0: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
95d0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
95e0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
95f0: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9600: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9610: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9620: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9630: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9640: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9650: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9660: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9670: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9680: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9690: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
96a0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
96b0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
96c0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
96d0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
96e0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
96f0: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9700: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9710: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9720: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9730: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9740: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9750: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
9760: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
9770: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
9780: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
9790: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
97a0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
97b0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
97c0: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
97d0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
97e0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
97f0: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
9800: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
9810: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
9820: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
9830: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
9840: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
9850: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
9860: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
9870: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
9880: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
9890: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
98a0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
98b0: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
98c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
98d0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
98e0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
98f0: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
9900: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9910: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
9920: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
9930: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
9940: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
9950: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9960: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
9970: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9980: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9990: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
99a0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
99b0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
99c0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
99d0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
99e0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
99f0: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
9a00: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
9a10: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9a20: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9a30: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9a40: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9a50: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
9a60: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9a70: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9a80: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9a90: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9aa0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9ab0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9ac0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
9ad0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9ae0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9af0: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
9b00: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
9b10: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9b20: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9b30: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
9b40: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
9b50: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9b60: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
9b70: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
9b80: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
9b90: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9ba0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9bb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9bc0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9bd0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9be0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9bf0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9c00: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9c10: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
9c20: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
9c30: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
9c40: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
9c50: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9c60: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9c70: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9c80: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9c90: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
9ca0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
9cb0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9cc0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
9cd0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9ce0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9cf0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
9d00: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
9d10: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
9d20: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
9d30: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
9d40: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
9d50: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
9d60: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
9d70: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
9d80: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
9d90: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
9da0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
9db0: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
9dc0: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
9dd0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
9de0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9df0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
9e00: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
9e10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
9e20: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
9e30: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
9e40: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
9e50: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
9e60: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
9e70: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
9e80: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
9e90: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
9ea0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
9eb0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
9ec0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
9ed0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
9ee0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
9ef0: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
9f00: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
9f10: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
9f20: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
9f30: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
9f40: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9f50: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
9f60: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
9f70: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
9f80: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
9f90: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
9fa0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
9fb0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
9fc0: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
9fd0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
9fe0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
9ff0: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a000: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a010: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a020: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a030: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a040: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a050: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a060: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a070: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a080: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a090: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a0a0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a0b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a0c0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a0d0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
a0e0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a0f0: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
a100: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
a110: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
a120: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
a130: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
a140: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
a150: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
a160: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
a170: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
a180: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
a190: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
a1a0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
a1b0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
a1c0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a1d0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
a1e0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
a1f0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
a200: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
a210: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
a220: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
a230: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
a240: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
a250: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
a260: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
a270: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
a280: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
a290: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
a2a0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
a2b0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
a2c0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
a2d0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a2e0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
a2f0: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
a300: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
a310: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
a320: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
a330: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
a340: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a350: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
a360: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
a370: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
a380: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
a390: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
a3a0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
a3b0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
a3c0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
a3d0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
a3e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a3f0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a400: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a410: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
a420: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
a430: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
a440: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
a450: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a460: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a470: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a480: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
a490: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
a4a0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
a4b0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
a4c0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
a4d0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
a4e0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
a4f0: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
a500: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
a510: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a520: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a530: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a540: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
a550: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
a560: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
a570: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a580: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
a590: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
a5a0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
a5b0: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
a5c0: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
a5d0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
a5e0: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
a5f0: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
a600: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
a610: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a620: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
a630: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
a640: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
a650: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
a660: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
a670: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
a680: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
a690: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
a6a0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
a6b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a6c0: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
a6d0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a6e0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
a6f0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
a700: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
a710: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
a720: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
a730: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
a740: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
a750: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
a760: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
a770: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
a780: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
a790: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
a7a0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
a7b0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
a7c0: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
a7d0: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
a7e0: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
a7f0: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
a800: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
a810: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
a820: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
a830: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
a840: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
a850: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
a860: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
a870: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
a880: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
a890: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
a8a0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
a8b0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
a8c0: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
a8d0: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
a8e0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
a8f0: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
a900: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
a910: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
a920: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
a930: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
a940: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
a950: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
a960: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
a970: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
a980: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
a990: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
a9a0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
a9b0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
a9c0: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
a9d0: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
a9e0: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
a9f0: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
aa00: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
aa10: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
aa20: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
aa30: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
aa40: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
aa50: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
aa60: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
aa70: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
aa80: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
aa90: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
aaa0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
aab0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
aac0: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
aad0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
aae0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
aaf0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ab00: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
ab10: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
ab20: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
ab30: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
ab40: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
ab50: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
ab60: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
ab70: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
ab80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ab90: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
aba0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
abb0: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
abc0: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
abd0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
abe0: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
abf0: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
ac00: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
ac10: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
ac20: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
ac30: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
ac40: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
ac50: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
ac60: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
ac70: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
ac80: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
ac90: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
aca0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
acb0: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
acc0: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
acd0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
ace0: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
acf0: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
ad00: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
ad10: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
ad20: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
ad30: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
ad40: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
ad50: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
ad60: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
ad70: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
ad80: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
ad90: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
ada0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
adb0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a  e]..**.** </ul>.
adc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
add0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
ade0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
adf0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
ae00: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
ae10: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
ae20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ae30: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
ae40: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
ae50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
ae60: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
ae70: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
ae80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ae90: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
aea0: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
aeb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
aec0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
aed0: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
aee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
aef0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
af00: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
af10: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
af20: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
af30: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
af40: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
af50: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
af60: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
af70: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
af80: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
af90: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
afa0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
afb0: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
afc0: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
afd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
afe0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
aff0: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
b000: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
b010: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b020: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
b030: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b040: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
b050: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
b060: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b070: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
b080: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
b090: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b0a0: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
b0b0: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
b0c0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b0d0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b0e0: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
b0f0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
b100: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
b110: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
b120: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
b130: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
b140: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
b150: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
b160: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
b170: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
b180: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
b190: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
b1a0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
b1b0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
b1c0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
b1d0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
b1e0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
b1f0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
b200: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
b210: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
b220: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
b230: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
b240: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
b250: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
b260: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
b270: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
b280: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
b290: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
b2a0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
b2b0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
b2c0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
b2d0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
b2e0: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
b2f0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
b300: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
b310: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
b320: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
b330: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
b340: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
b350: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
b360: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
b370: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
b380: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
b390: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
b3a0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
b3b0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
b3c0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
b3d0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
b3e0: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
b3f0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
b400: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
b410: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
b420: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
b430: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
b440: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
b450: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
b460: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
b470: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
b480: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
b490: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
b4a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
b4b0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
b4c0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
b4d0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
b4e0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
b4f0: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
b500: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
b510: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
b520: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
b530: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
b540: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
b550: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
b560: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
b570: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
b580: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
b590: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
b5a0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
b5b0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
b5c0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
b5d0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
b5e0: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
b5f0: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
b600: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
b610: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
b620: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
b630: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
b640: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
b650: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
b660: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
b670: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
b680: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
b690: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
b6a0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
b6b0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
b6c0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
b6d0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
b6e0: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
b6f0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
b700: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
b710: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
b720: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
b730: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
b740: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
b750: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
b760: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
b770: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
b780: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
b790: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
b7a0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
b7b0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
b7c0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
b7d0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
b7e0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
b7f0: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
b800: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
b810: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
b820: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
b830: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
b840: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
b850: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
b860: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
b870: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
b880: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
b890: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
b8a0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
b8b0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
b8c0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
b8d0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
b8e0: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
b8f0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
b900: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
b910: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
b920: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
b930: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
b940: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
b950: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
b960: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
b970: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
b980: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
b990: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
b9a0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
b9b0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
b9c0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
b9d0: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
b9e0: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
b9f0: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
ba00: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
ba10: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
ba20: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
ba30: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
ba40: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
ba50: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
ba60: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
ba70: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
ba80: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
ba90: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
baa0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
bab0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
bac0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
bad0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
bae0: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
baf0: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
bb00: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
bb10: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
bb20: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
bb30: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
bb40: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
bb50: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
bb60: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
bb70: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
bb80: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
bb90: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
bba0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
bbb0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
bbc0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
bbd0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
bbe0: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
bbf0: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
bc00: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
bc10: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
bc20: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
bc30: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
bc40: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
bc50: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
bc60: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
bc70: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
bc80: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
bc90: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
bca0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
bcb0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
bcc0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
bcd0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
bce0: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
bcf0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
bd00: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
bd10: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
bd20: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
bd30: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
bd40: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
bd50: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
bd60: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
bd70: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
bd80: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
bd90: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
bda0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
bdb0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
bdc0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
bdd0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
bde0: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
bdf0: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
be00: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
be10: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
be20: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
be30: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
be40: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
be50: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
be60: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
be70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
be80: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
be90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
bea0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
beb0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
bec0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
bed0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
bee0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
bef0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
bf00: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
bf10: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
bf20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
bf30: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
bf40: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
bf50: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
bf60: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
bf70: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
bf80: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
bf90: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
bfa0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
bfb0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
bfc0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
bfd0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
bfe0: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
bff0: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
c000: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
c010: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
c020: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
c030: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
c040: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
c050: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
c060: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
c070: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
c080: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
c090: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
c0a0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
c0b0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
c0c0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
c0d0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
c0e0: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
c0f0: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
c100: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
c110: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
c120: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
c130: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
c140: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
c150: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
c160: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
c170: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
c180: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
c190: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
c1a0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
c1b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
c1c0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
c1d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
c1e0: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
c1f0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
c200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c210: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
c220: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
c230: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
c240: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
c250: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
c260: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c270: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
c280: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
c290: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
c2a0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
c2b0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
c2c0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
c2d0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
c2e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
c2f0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
c300: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
c310: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
c320: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
c330: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
c340: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
c350: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
c360: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
c370: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
c380: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
c390: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
c3a0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
c3b0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
c3c0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
c3d0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
c3e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
c3f0: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
c400: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
c410: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
c420: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
c430: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
c440: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
c450: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
c460: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
c470: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
c480: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
c490: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
c4a0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
c4b0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
c4c0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
c4d0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
c4e0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
c4f0: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
c500: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
c510: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
c520: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
c530: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
c540: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
c550: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
c560: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
c570: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
c580: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
c590: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
c5a0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
c5b0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
c5c0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
c5d0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
c5e0: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
c5f0: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
c600: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
c610: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
c620: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
c630: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
c640: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
c650: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
c660: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
c670: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
c680: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
c690: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
c6a0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
c6b0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
c6c0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
c6d0: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
c6e0: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
c6f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
c700: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
c710: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
c720: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
c730: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
c740: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
c750: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
c760: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
c770: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
c780: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
c790: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
c7a0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
c7b0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
c7c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
c7d0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
c7e0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
c7f0: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
c800: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
c810: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
c820: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
c830: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
c840: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
c850: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
c860: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
c870: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
c880: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
c890: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
c8a0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
c8b0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
c8c0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
c8d0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
c8e0: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
c8f0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
c900: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
c910: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
c920: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
c930: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
c940: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
c950: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
c960: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
c970: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
c980: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
c990: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
c9a0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
c9b0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
c9c0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
c9d0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
c9e0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
c9f0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
ca00: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
ca10: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
ca20: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
ca30: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
ca40: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
ca50: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
ca60: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
ca70: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
ca80: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
ca90: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
caa0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
cab0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
cac0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
cad0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
cae0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
caf0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
cb00: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
cb10: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
cb20: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
cb30: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
cb40: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
cb50: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
cb60: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
cb70: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
cb80: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
cb90: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
cba0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
cbb0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
cbc0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
cbd0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
cbe0: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
cbf0: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
cc00: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
cc10: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
cc20: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
cc30: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
cc40: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
cc50: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
cc60: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
cc70: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
cc80: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
cc90: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
cca0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
ccb0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
ccc0: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
ccd0: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
cce0: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
ccf0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
cd00: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
cd10: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
cd20: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
cd30: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
cd40: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
cd50: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
cd60: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
cd70: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
cd80: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
cd90: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
cda0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
cdb0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
cdc0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
cdd0: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
cde0: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
cdf0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
ce00: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
ce10: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
ce20: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
ce30: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
ce40: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
ce50: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
ce60: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
ce70: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
ce80: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
ce90: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
cea0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
ceb0: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
cec0: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
ced0: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
cee0: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
cef0: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
cf00: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
cf10: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
cf20: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
cf30: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
cf40: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
cf50: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
cf60: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
cf70: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
cf80: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
cf90: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
cfa0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
cfb0: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
cfc0: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
cfd0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
cfe0: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
cff0: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
d000: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
d010: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
d020: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
d030: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
d040: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
d050: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
d060: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
d070: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
d080: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
d090: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
d0a0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
d0b0: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
d0c0: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
d0d0: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
d0e0: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
d0f0: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
d100: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
d110: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d120: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
d130: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
d140: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
d150: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
d160: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
d170: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
d180: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
d190: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
d1a0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
d1b0: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
d1c0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
d1d0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
d1e0: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
d1f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
d200: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
d210: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
d220: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
d230: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
d240: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
d250: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
d260: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
d270: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
d280: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
d290: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
d2a0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
d2b0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
d2c0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
d2d0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
d2e0: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
d2f0: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
d300: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
d310: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
d320: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
d330: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
d340: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
d350: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
d360: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
d370: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
d380: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d390: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
d3a0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
d3b0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
d3c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d3d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
d3e0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
d3f0: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
d400: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
d410: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d420: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
d430: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
d440: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
d450: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
d460: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
d470: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
d480: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
d490: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
d4a0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
d4b0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
d4c0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
d4d0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
d4e0: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
d4f0: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
d500: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
d510: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
d520: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
d530: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
d540: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
d550: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
d560: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
d570: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
d580: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
d590: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
d5a0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
d5b0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
d5c0: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
d5d0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
d5e0: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
d5f0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
d600: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
d610: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
d620: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
d630: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
d640: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
d650: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
d660: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
d670: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
d680: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
d690: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
d6a0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
d6b0: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
d6c0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
d6d0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
d6e0: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
d6f0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
d700: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
d710: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
d720: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
d730: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
d740: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
d750: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d760: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d770: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
d780: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
d790: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
d7a0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
d7b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d7c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d7d0: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
d7e0: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
d7f0: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
d800: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d810: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
d820: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
d830: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
d840: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
d850: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
d860: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
d870: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
d880: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
d890: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
d8a0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
d8b0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
d8c0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
d8d0: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
d8e0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d8f0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
d900: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
d910: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
d920: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
d930: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
d940: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
d950: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
d960: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
d970: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
d980: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
d990: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
d9a0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
d9b0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
d9c0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
d9d0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
d9e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
d9f0: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
da00: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
da10: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
da20: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
da30: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
da40: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
da50: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
da60: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
da70: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
da80: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
da90: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
daa0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
dab0: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
dac0: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
dad0: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
dae0: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
daf0: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
db00: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
db10: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
db20: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
db30: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
db40: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
db50: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
db60: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
db70: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
db80: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
db90: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
dba0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
dbb0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
dbc0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
dbd0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
dbe0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
dbf0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
dc00: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
dc10: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
dc20: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
dc30: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
dc40: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
dc50: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
dc60: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
dc70: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
dc80: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
dc90: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
dca0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
dcb0: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
dcc0: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
dcd0: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
dce0: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
dcf0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
dd00: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
dd10: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
dd20: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
dd30: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
dd40: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
dd50: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
dd60: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
dd70: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
dd80: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
dd90: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
dda0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ddb0: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
ddc0: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
ddd0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
dde0: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
ddf0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
de00: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
de10: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
de20: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
de30: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
de40: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
de50: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
de60: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
de70: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
de80: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
de90: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
dea0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
deb0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
dec0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
ded0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
dee0: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
def0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
df00: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
df10: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
df20: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
df30: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
df40: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
df50: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
df60: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
df70: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
df80: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
df90: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
dfa0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
dfb0: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
dfc0: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
dfd0: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
dfe0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
dff0: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
e000: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
e010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e020: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
e030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e040: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
e050: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
e060: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
e070: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
e080: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
e090: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
e0a0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
e0b0: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
e0c0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
e0d0: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
e0e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
e0f0: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
e100: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
e110: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
e120: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
e130: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
e140: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
e150: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
e160: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
e170: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
e180: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
e190: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
e1a0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
e1b0: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
e1c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
e1d0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
e1e0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
e1f0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
e200: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
e210: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
e220: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
e230: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
e240: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e250: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
e260: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
e270: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
e280: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
e290: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e2a0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
e2b0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
e2c0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
e2d0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
e2e0: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
e2f0: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
e300: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
e310: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
e320: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
e330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
e340: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
e350: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
e360: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
e370: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
e380: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e390: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
e3a0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
e3b0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
e3c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e3d0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
e3e0: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
e3f0: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
e400: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
e410: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
e420: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
e430: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
e440: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
e450: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
e460: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
e470: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
e480: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
e490: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e4a0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
e4b0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
e4c0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
e4d0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
e4e0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
e4f0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
e500: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
e510: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
e520: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
e530: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
e540: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e550: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
e560: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
e570: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
e580: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
e590: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
e5a0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
e5b0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
e5c0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
e5d0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
e5e0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e5f0: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
e600: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
e610: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
e620: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
e630: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
e640: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
e650: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
e660: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
e670: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
e680: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
e690: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
e6a0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
e6b0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
e6c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e6d0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
e6e0: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
e6f0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
e700: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
e710: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
e720: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
e730: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e740: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
e750: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
e760: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e770: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
e780: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
e790: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
e7a0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
e7b0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
e7c0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
e7d0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
e7e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e7f0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
e800: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
e810: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
e820: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
e830: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
e840: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
e850: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
e860: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
e870: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
e880: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
e890: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
e8a0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
e8b0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
e8c0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
e8d0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
e8e0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
e8f0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
e900: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
e910: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
e920: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
e930: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
e940: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
e950: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
e960: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
e970: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
e980: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
e990: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
e9a0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
e9b0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
e9c0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
e9d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e9e0: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
e9f0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
ea00: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
ea10: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
ea20: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
ea30: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
ea40: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
ea50: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
ea60: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
ea70: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
ea80: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
ea90: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
eaa0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
eab0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
eac0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
ead0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
eae0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eaf0: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
eb00: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
eb10: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
eb20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eb30: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
eb40: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
eb50: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
eb60: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
eb70: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
eb80: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
eb90: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
eba0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
ebb0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
ebc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
ebd0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
ebe0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ebf0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ec00: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
ec10: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
ec20: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
ec30: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
ec40: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
ec50: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
ec60: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
ec70: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
ec80: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ec90: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
eca0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
ecb0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
ecc0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
ecd0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
ece0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
ecf0: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
ed00: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
ed10: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
ed20: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
ed30: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
ed40: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
ed50: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
ed60: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
ed70: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
ed80: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
ed90: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
eda0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
edb0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
edc0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
edd0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
ede0: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
edf0: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
ee00: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
ee10: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
ee20: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
ee30: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
ee40: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
ee50: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
ee60: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
ee70: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
ee80: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
ee90: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
eea0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
eeb0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
eec0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
eed0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
eee0: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
eef0: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
ef00: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
ef10: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
ef20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
ef30: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
ef40: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
ef50: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
ef60: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
ef70: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
ef80: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
ef90: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
efa0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
efb0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
efc0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
efd0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
efe0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
eff0: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
f000: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
f010: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
f020: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
f030: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
f040: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
f050: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
f060: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
f070: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
f080: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
f090: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
f0a0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
f0b0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
f0c0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
f0d0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
f0e0: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
f0f0: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
f100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
f110: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
f120: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
f130: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
f140: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
f150: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
f160: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
f170: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
f180: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
f190: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
f1a0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
f1b0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
f1c0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
f1d0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
f1e0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f1f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
f200: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
f210: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
f220: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
f230: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
f240: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
f250: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
f260: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
f270: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
f280: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
f290: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f2a0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
f2b0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
f2c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
f2d0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
f2e0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
f2f0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
f300: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
f310: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
f320: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
f330: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f340: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
f350: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
f360: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
f370: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
f380: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
f390: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
f3a0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
f3b0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
f3c0: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
f3d0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
f3e0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
f3f0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
f400: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
f410: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
f420: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
f430: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
f440: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
f450: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
f460: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
f470: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
f480: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
f490: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
f4a0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
f4b0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
f4c0: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
f4d0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
f4e0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
f4f0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
f500: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
f510: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
f520: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
f530: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
f540: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f550: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
f560: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
f570: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
f580: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
f590: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
f5a0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
f5b0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
f5c0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
f5d0: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
f5e0: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
f5f0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
f600: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
f610: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
f620: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
f630: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
f640: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
f650: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
f660: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f670: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
f680: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
f690: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
f6a0: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
f6b0: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
f6c0: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
f6d0: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
f6e0: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
f6f0: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
f700: 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
f710: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
f720: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
f730: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
f740: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
f750: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
f760: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
f770: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
f780: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
f790: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
f7a0: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
f7b0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
f7c0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
f7d0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
f7e0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
f7f0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
f800: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
f810: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
f820: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
f830: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
f840: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f850: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
f860: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f870: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f880: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
f890: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
f8a0: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
f8b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f8c0: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
f8d0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
f8e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f8f0: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
f900: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
f910: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
f920: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
f930: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
f940: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
f950: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
f960: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
f970: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
f980: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
f990: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
f9a0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
f9b0: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
f9c0: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
f9d0: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
f9e0: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
f9f0: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
fa00: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
fa10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
fa20: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
fa30: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
fa40: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
fa50: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
fa60: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
fa70: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
fa80: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
fa90: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
faa0: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
fab0: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
fac0: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
fad0: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
fae0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
faf0: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
fb00: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
fb10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fb20: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
fb30: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
fb40: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
fb50: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
fb60: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
fb70: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
fb80: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
fb90: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
fba0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
fbb0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
fbc0: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
fbd0: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
fbe0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fbf0: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
fc00: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
fc10: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
fc20: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
fc30: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
fc40: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
fc50: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fc60: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
fc70: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
fc80: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
fc90: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
fca0: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
fcb0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
fcc0: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
fcd0: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
fce0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fcf0: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
fd00: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
fd10: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
fd20: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
fd30: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
fd40: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
fd50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fd60: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
fd70: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
fd80: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
fd90: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
fda0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
fdb0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
fdc0: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
fdd0: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
fde0: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
fdf0: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
fe00: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
fe10: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
fe20: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
fe30: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
fe40: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
fe50: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
fe60: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
fe70: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
fe80: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
fe90: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
fea0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
feb0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
fec0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
fed0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
fee0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
fef0: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
ff00: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
ff10: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
ff20: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
ff30: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
ff40: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
ff50: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
ff60: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
ff70: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
ff80: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
ff90: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
ffa0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
ffb0: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
ffc0: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
ffd0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
ffe0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
fff0: 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
10000 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10010 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10020 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10030 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10040 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10050 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10060 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
10070 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10080 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10090 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
100a0 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
100b0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
100c0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
100d0 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
100e0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
100f0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
10100 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10110 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
10120 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
10130 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
10140 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
10150 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
10160 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
10170 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
10180 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
10190 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
101a0 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
101b0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
101c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
101d0 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
101e0 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
101f0 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
10200 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10210 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
10220 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
10230 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
10240 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
10250 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
10260 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
10270 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
10280 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
10290 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
102a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
102b0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
102c0 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
102d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
102e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
102f0 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
10300 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
10310 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
10320 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
10330 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
10340 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
10350 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
10360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
10370 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
10380 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
10390 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
103a0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
103b0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
103c0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
103d0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
103e0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
103f0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
10400 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
10410 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
10420 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
10430 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10440 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
10450 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
10460 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
10470 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
10480 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
10490 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
104a0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
104b0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
104c0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
104d0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
104e0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
104f0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
10500 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
10510 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
10520 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
10530 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
10540 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
10550 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
10560 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
10570 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
10580 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
10590 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
105a0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
105b0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
105c0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
105d0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
105e0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
105f0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
10600 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
10610 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
10620 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
10630 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
10640 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
10650 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
10660 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
10670 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
10680 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
10690 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
106a0 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
106b0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
106c0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
106d0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
106e0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
106f0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
10700 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
10710 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
10720 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
10730 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
10740 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
10750 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
10760 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
10770 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
10780 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
10790 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
107a0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
107b0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
107c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
107d0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
107e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
107f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
10800 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
10810 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
10820 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
10830 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
10840 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
10850 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
10860 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
10870 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
10880 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
10890 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
108a0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
108b0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
108c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
108d0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
108e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
108f0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
10900 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
10910 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
10920 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
10930 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
10940 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
10950 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
10960 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
10970 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
10980 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
10990 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
109a0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
109b0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
109c0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
109d0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
109e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
109f0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
10a00 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
10a10 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
10a20 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
10a30 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
10a40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10a50 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
10a60 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
10a70 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
10a80 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
10a90 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
10aa0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
10ab0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
10ac0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10ad0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
10ae0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
10af0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10b00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
10b10 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10b20 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
10b30 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10b40 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
10b50 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
10b60 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
10b70 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
10b80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10b90 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
10ba0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
10bb0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
10bc0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
10bd0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
10be0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
10bf0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
10c00 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
10c10 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
10c20 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
10c30 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
10c40 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
10c50 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
10c60 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
10c70 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
10c80 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10c90 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
10ca0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
10cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
10cc0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
10cd0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
10ce0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
10cf0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10d00 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10d10 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10d20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
10d30 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10d40 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
10d50 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
10d60 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
10d70 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
10d80 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
10d90 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
10da0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
10db0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
10dc0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
10dd0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
10de0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10df0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10e00 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10e10 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10e20 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10e30 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10e40 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
10e50 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
10e60 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
10e70 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
10e80 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
10e90 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
10ea0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
10eb0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
10ec0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
10ed0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
10ee0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
10ef0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
10f00 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
10f10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
10f20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
10f30 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10f40 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
10f50 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10f60 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
10f70 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
10f80 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
10f90 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
10fa0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
10fb0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
10fc0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
10fd0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
10fe0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
10ff0 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
11000 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11010 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
11020 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
11030 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
11040 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
11050 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
11060 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
11070 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
11080 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
11090 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
110a0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
110b0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
110c0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
110d0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
110e0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
110f0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
11100 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
11110 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
11120 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
11130 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
11140 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
11150 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
11160 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
11170 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11180 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11190 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
111a0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
111b0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
111c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
111d0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
111e0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
111f0 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
11200 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
11210 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
11220 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11230 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
11240 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
11250 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
11260 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11270 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
11280 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
11290 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
112a0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
112b0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
112c0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
112d0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
112e0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
112f0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11300 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11310 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11320 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11330 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
11340 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11350 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
11360 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
11370 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
11380 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
11390 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
113a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
113b0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
113c0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
113d0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
113e0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
113f0 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
11400 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11410 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
11420 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
11430 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
11440 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
11450 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
11460 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
11470 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11480 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11490 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
114a0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
114b0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
114c0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
114d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
114e0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
114f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11500 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
11510 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
11520 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
11530 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11540 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11550 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11560 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11570 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11580 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11590 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
115a0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
115b0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
115c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
115d0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
115e0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
115f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
11600 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11610 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
11620 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
11630 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
11640 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11650 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11660 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
11670 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11680 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
11690 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
116a0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
116b0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
116c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
116d0 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
116e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
116f0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
11700 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
11710 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
11720 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
11730 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
11740 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11750 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
11760 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
11770 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11780 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
11790 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
117a0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
117b0 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
117c0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
117d0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
117e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
117f0 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
11800 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
11810 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
11820 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
11830 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11840 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11850 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11860 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
11870 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
11880 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11890 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
118a0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
118b0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
118c0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
118d0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
118e0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
118f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
11900 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
11910 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
11920 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
11930 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
11940 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
11950 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
11960 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
11970 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
11980 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
11990 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
119a0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
119b0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
119c0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
119d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
119e0 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
119f0 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
11a00 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
11a10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11a20 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11a30 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
11a40 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11a50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11a60 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11a70 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11a80 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
11a90 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
11aa0 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
11ab0 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
11ac0 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
11ad0 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
11ae0 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
11af0 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
11b00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11b10 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11b20 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
11b30 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
11b40 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
11b50 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
11b60 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
11b70 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
11b80 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
11b90 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
11ba0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
11bb0 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
11bc0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
11bd0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
11be0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
11bf0 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
11c00 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
11c10 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
11c20 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11c30 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
11c40 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
11c50 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
11c60 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
11c70 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
11c80 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
11c90 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
11ca0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
11cb0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
11cc0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
11cd0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11ce0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
11cf0 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
11d00 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
11d10 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11d20 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
11d30 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
11d40 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
11d50 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
11d60 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
11d70 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
11d80 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
11d90 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
11da0 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
11db0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
11dc0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
11dd0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
11de0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
11df0 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
11e00 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
11e10 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
11e20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
11e30 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
11e40 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
11e50 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
11e60 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
11e70 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
11e80 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
11e90 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
11ea0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
11eb0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
11ec0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
11ed0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
11ee0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
11ef0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
11f00 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
11f10 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
11f20 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
11f30 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
11f40 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
11f50 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
11f60 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
11f70 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
11f80 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
11f90 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
11fa0 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
11fb0 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
11fc0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
11fd0 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
11fe0 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
11ff0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
12000 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
12010 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12020 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
12030 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
12040 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
12050 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
12060 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
12070 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
12080 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
12090 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
120a0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
120b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
120c0 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
120d0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
120e0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
120f0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12100 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
12110 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
12120 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12130 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
12140 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
12150 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12160 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
12170 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
12180 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
12190 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
121a0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
121b0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
121c0 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
121d0 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
121e0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
121f0 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
12200 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
12210 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12220 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
12230 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
12240 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
12250 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
12260 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
12270 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
12280 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
12290 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
122a0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
122b0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
122c0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
122d0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
122e0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
122f0 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
12300 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
12310 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
12320 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
12330 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
12340 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
12350 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
12360 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
12370 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
12380 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
12390 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
123a0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
123b0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
123c0 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
123d0 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
123e0 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
123f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
12400 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12410 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12420 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
12430 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
12440 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
12450 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
12460 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
12470 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
12480 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
12490 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
124a0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
124b0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
124c0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
124d0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
124e0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
124f0 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
12500 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
12510 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
12520 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
12530 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
12540 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
12550 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
12560 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12570 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
12580 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
12590 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
125a0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
125b0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
125c0 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
125d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
125e0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
125f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12600 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
12610 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12620 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12630 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12640 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
12650 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
12660 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
12670 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
12680 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
12690 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
126a0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
126b0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
126c0 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
126d0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
126e0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
126f0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
12700 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
12710 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
12720 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
12730 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
12740 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
12750 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
12760 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12770 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
12780 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
12790 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
127a0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
127b0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
127c0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
127d0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
127e0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
127f0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
12800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
12810 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
12820 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
12830 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
12840 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
12850 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
12860 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
12870 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
12880 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
12890 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
128a0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
128b0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
128c0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
128d0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
128e0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
128f0 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
12900 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
12910 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12920 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
12930 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
12940 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
12950 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
12960 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
12970 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
12980 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
12990 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
129a0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
129b0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
129c0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
129d0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
129e0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
129f0 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
12a00 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12a10 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
12a20 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
12a30 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12a40 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
12a50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12a60 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
12a70 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12a80 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12a90 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12aa0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12ab0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
12ac0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12ad0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12ae0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
12af0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
12b00 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
12b10 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
12b20 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
12b30 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
12b40 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
12b50 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
12b60 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
12b70 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
12b80 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
12b90 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12ba0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
12bb0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
12bc0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
12bd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12be0 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
12bf0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12c00 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12c10 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12c20 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12c30 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12c40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12c50 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
12c60 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
12c70 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
12c80 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
12c90 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
12ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12cb0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
12cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
12cd0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
12ce0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
12cf0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12d00 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
12d10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12d20 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
12d30 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12d40 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
12d50 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12d60 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12d70 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12d80 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12d90 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
12da0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12db0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12dc0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
12dd0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
12de0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12df0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12e00 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12e10 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
12e20 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
12e30 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
12e40 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
12e50 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
12e60 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
12e70 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
12e80 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
12e90 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
12ea0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
12eb0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
12ec0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
12ed0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
12ee0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12ef0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12f00 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12f10 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12f20 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12f30 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12f40 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
12f50 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
12f60 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
12f70 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
12f80 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
12f90 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12fa0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
12fb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12fc0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
12fd0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
12fe0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
12ff0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13000 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13010 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13020 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
13030 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
13040 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13050 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13060 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
13070 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
13080 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
13090 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
130a0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
130b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
130c0 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
130d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
130e0 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
130f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
13100 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
13110 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
13120 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
13130 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
13140 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
13150 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
13160 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13170 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
13180 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
13190 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
131a0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
131b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
131c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
131d0 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
131e0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
131f0 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
13200 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
13210 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
13220 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
13230 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
13240 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
13250 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13260 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
13270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13280 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
13290 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
132a0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
132b0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
132c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
132d0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
132e0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
132f0 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
13300 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
13310 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
13320 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
13330 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13340 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
13350 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
13360 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
13370 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
13380 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
13390 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
133a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
133b0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
133c0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
133d0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
133e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
133f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13400 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13410 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
13420 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
13430 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13440 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13450 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
13460 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
13470 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
13480 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
13490 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
134a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
134b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
134c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
134d0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
134e0 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
134f0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
13500 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
13510 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
13520 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
13530 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
13540 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13550 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
13560 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
13570 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
13580 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
13590 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
135a0 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
135b0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
135c0 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
135d0 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
135e0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
135f0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13600 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
13610 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
13620 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
13630 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
13640 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
13650 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
13660 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
13670 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
13680 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
13690 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
136a0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
136b0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
136c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
136d0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
136e0 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
136f0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
13700 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
13710 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
13720 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
13730 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
13740 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
13750 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
13760 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
13770 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
13780 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
13790 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
137a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
137b0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
137c0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
137d0 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
137e0 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
137f0 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
13800 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
13810 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
13820 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
13830 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
13840 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
13850 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
13860 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
13870 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
13880 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
13890 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
138a0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
138b0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
138c0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
138d0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
138e0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
138f0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
13900 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
13910 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
13920 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
13930 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
13940 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
13950 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
13960 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
13970 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
13980 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13990 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
139a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
139b0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69  _URI.** <dd> Thi
139c0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
139d0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
139e0 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
139f0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
13a00 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
13a10 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
13a20 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
13a30 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
13a40 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
13a50 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
13a60 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49  disabled. If URI
13a70 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13a80 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
13a90 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
13aa0 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
13ab0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
13ac0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
13ad0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
13ae0 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
13af0 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
13b00 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
13b10 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
13b20 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
13b30 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
13b40 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
13b50 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
13b60 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
13b70 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
13b80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
13b90 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20  pened. If it is 
13ba0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
13bb0 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
13bc0 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
13bd0 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
13be0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
13bf0 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
13c00 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
13c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
13c20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65  is opened. By de
13c30 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
13c40 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
13c50 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
13c60 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
13c70 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
13c80 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
13c90 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
13ca0 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
13cb0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efined..**.** [[
13cc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
13cd0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
13ce0 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
13cf0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
13d00 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
13d10 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
13d20 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
13d30 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68  eger argument wh
13d40 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
13d50 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65  ed as.** a boole
13d60 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
13d70 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
13d80 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
13d90 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
13da0 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  .** full table s
13db0 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
13dc0 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68  y optimizer.  Th
13dd0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
13de0 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
13df0 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
13e00 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
13e10 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
13e20 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13e30 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
13e40 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
13e50 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
13e60 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
13e70 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
13e80 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
13e90 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
13ea0 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
13eb0 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
13ec0 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
13ed0 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
13ee0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
13ef0 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
13f00 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65   malfunction whe
13f10 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
13f20 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
13f30 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
13f40 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
13f50 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
13f60 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
13f70 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
13f80 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
13f90 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
13fa0 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
13fb0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
13fc0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
13fd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13fe0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
13ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14000 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
14010 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14020 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
14030 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
14040 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
14050 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
14060 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
14070 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
14080 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
14090 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
140a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
140b0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
140c0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
140d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
140e0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
140f0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14100 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
14110 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
14120 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
14130 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
14140 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
14150 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
14160 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
14170 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
14180 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
14190 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
141a0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
141b0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
141c0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
141d0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
141e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
141f0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
14200 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
14210 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
14220 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
14230 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
14240 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
14250 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
14260 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
14270 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
14280 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
14290 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
142a0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
142b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
142c0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
142d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
142e0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
142f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
14300 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
14310 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
14320 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
14330 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
14340 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
14350 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
14360 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
14370 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
14380 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
14390 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
143a0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
143b0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
143c0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
143d0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
143e0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
143f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
14400 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
14410 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
14420 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
14430 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14440 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
14450 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
14460 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
14470 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
14480 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
14490 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
144a0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
144b0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
144c0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
144d0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
144e0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
144f0 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
14500 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
14510 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14520 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
14530 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
14540 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
14550 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51 4c 49  SIZE.** <dd>SQLI
14560 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
14570 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
14580 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
14590 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
145a0 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
145b0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
145c0 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
145d0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
145e0 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
145f0 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
14600 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
14610 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
14620 6d 69 74 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  mit..** The defa
14630 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
14640 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
14650 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14660 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
14670 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
14680 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
14690 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
146a0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
146b0 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
146c0 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
146d0 6f 6c 2e 20 20 54 68 65 20 6d 61 78 69 6d 75 6d  ol.  The maximum
146e0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
146f0 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  ze.** cannot be 
14700 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74  changed at run-t
14710 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68  ime.  Nor may th
14720 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
14730 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65  d mmap size.** e
14740 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c  xceed the compil
14750 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
14760 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
14770 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
14780 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
14790 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
147a0 6e 2e 20 20 0a 2a 2a 20 49 66 20 65 69 74 68 65  n.  .** If eithe
147b0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
147c0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
147d0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
147e0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
147f0 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
14800 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
14810 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ult..** </dl>.*/
14820 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14830 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
14840 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
14850 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14860 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
14870 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
14880 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14890 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
148a0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
148b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
148c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
148d0 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
148e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
148f0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
14900 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14910 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
14920 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14930 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14950 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
14960 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
14970 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
14980 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14990 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
149a0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
149b0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
149c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
149d0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
149e0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
149f0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
14a00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14a10 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14a20 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
14a30 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
14a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14a50 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
14a60 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
14a70 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
14a80 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14a90 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
14aa0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
14ab0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
14ac0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
14ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
14ae0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
14af0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
14b00 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
14b10 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14b20 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
14b30 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14b40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14b50 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
14b60 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
14b70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14b80 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
14b90 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
14ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14bb0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
14bc0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
14bd0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
14be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
14bf0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
14c00 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
14c10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14c20 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
14c30 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
14c40 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
14c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14c60 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
14c70 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
14c80 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14c90 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14cb0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
14cc0 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
14cd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14ce0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
14cf0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
14d00 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
14d10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14d20 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
14d30 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
14d40 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
14d50 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
14d60 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
14d70 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
14d80 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
14d90 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
14da0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
14db0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
14dc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14dd0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
14de0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
14df0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14e00 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
14e10 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
14e20 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
14e30 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
14e40 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
14e50 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
14e60 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
14e70 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
14e80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14e90 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
14ea0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
14eb0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
14ec0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
14ed0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
14ee0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14ef0 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
14f00 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
14f10 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
14f20 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
14f30 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
14f40 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
14f50 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
14f60 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
14f70 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
14f80 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
14f90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
14fa0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
14fb0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
14fc0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14fd0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
14fe0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
14ff0 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
15000 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
15010 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
15020 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
15030 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
15040 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
15050 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
15060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15070 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
15080 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
15090 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
150a0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
150b0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
150c0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
150d0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
150e0 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
150f0 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
15100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15110 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
15120 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15130 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
15140 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
15150 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
15160 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
15170 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
15180 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
15190 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
151a0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
151b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
151c0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
151d0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
151e0 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
151f0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
15200 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
15210 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
15220 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
15230 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
15240 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
15250 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
15260 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
15270 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
15280 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
15290 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
152a0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
152b0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
152c0 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
152d0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
152e0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
152f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15300 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
15310 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
15320 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
15330 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
15340 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
15350 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
15360 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
15370 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
15380 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
15390 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
153a0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
153b0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
153c0 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
153d0 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
153e0 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
153f0 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
15400 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
15410 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
15420 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
15430 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
15440 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
15450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15460 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
15470 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
15480 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
15490 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
154a0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
154b0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
154c0 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
154d0 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
154e0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
154f0 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
15500 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
15510 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
15520 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
15530 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15540 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
15550 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
15560 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
15570 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
15580 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
15590 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
155a0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
155b0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
155c0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
155d0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
155e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
155f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
15600 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
15610 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
15620 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
15630 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
15640 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
15650 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
15660 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
15670 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
15680 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15690 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
156a0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
156b0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
156c0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
156d0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
156e0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
156f0 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
15700 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
15710 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
15720 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
15730 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
15740 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
15750 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
15760 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
15770 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
15780 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
15790 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
157a0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
157b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
157c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
157d0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
157e0 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
157f0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
15800 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
15810 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
15820 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
15830 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
15840 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
15850 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
15860 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
15870 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
15880 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
15890 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
158a0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
158b0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
158c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
158d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
158e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
158f0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
15900 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
15910 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
15920 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
15930 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
15940 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
15950 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
15960 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
15970 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
15980 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
15990 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
159a0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
159b0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
159c0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
159d0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
159e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
159f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
15a00 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
15a10 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
15a20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15a30 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
15a40 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
15a50 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
15a60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15a70 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
15a80 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
15a90 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
15aa0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
15ab0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
15ac0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
15ad0 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
15ae0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
15af0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
15b00 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
15b10 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
15b20 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
15b30 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
15b40 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
15b50 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
15b60 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
15b70 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
15b80 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
15b90 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
15ba0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
15bb0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
15bc0 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
15bd0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
15be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
15bf0 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
15c00 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
15c10 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61   in an SQLite ta
15c20 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65  ble has a unique
15c30 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
15c40 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
15c50 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
15c60 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
15c70 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
15c80 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
15c90 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
15ca0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
15cb0 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
15cc0 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
15cd0 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
15ce0 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
15cf0 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
15d00 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
15d10 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
15d20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
15d30 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
15d40 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
15d50 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
15d60 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
15d70 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
15d80 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
15d90 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ne returns the [
15da0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f  rowid] of the mo
15db0 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63  st recent.** suc
15dc0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
15dd0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
15de0 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74  se from the [dat
15df0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15e00 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
15e10 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73  t argument.  ^As
15e20 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
15e30 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72  on 3.7.7, this r
15e40 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72  outines.** recor
15e50 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  ds the last inse
15e60 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68  rt rowid of both
15e70 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73   ordinary tables
15e80 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61   and [virtual ta
15e90 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  bles]..** ^If no
15ea0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
15eb0 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
15ec0 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
15ed0 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
15ee0 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
15ef0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
15f00 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
15f10 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
15f20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
15f30 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
15f40 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
15f50 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
15f60 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
15f70 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
15f80 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
15f90 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
15fa0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
15fb0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
15fc0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
15fd0 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
15fe0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
15ff0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
16000 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
16010 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
16020 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
16030 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
16040 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
16050 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
16060 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
16070 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
16080 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
16090 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
160a0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
160b0 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
160c0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
160d0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
160e0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
160f0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
16100 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
16110 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
16120 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
16130 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
16140 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
16150 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
16160 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
16170 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
16180 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
16190 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
161a0 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
161b0 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
161c0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
161d0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
161e0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
161f0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
16200 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
16210 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
16220 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
16230 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
16240 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
16250 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
16260 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
16270 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
16280 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
16290 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
162a0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
162b0 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
162c0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
162d0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
162e0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
162f0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
16300 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
16310 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
16320 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
16330 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
16340 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
16350 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
16360 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
16370 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
16380 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
16390 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
163a0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
163b0 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
163c0 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
163d0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
163e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
163f0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
16400 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16410 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
16420 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
16430 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
16440 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
16450 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
16460 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
16470 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
16480 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16490 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
164a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
164b0 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
164c0 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
164d0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
164e0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
164f0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
16500 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
16510 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
16520 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
16530 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
16540 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
16550 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
16560 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
16570 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
16580 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
16590 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
165a0 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72  nged.** or inser
165b0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62  ted or deleted b
165c0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
165d0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51  tly completed SQ
165e0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f  L statement.** o
165f0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
16600 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
16610 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
16620 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
16630 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20   ^(Only changes 
16640 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
16650 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
16660 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  he [INSERT], [UP
16670 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45  DATE],.** or [DE
16680 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20  LETE] statement 
16690 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
166a0 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
166b0 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
166c0 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67  ggers or [foreig
166d0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
166e0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29  re not counted.)
166f0 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  ^ Use the.** [sq
16700 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
16710 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ges()] function 
16720 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
16730 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
16740 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67  ges.** including
16750 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
16760 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20  by triggers and 
16770 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
16780 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e  ons..**.** ^Chan
16790 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
167a0 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64  at are simulated
167b0 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20   by an [INSTEAD 
167c0 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61  OF trigger].** a
167d0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
167e0 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65   Only real table
167f0 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
16800 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20  nted..**.** ^(A 
16810 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20  "row change" is 
16820 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69  a change to a si
16830 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69  ngle row of a si
16840 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61  ngle table.** ca
16850 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52  used by an INSER
16860 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50  T, DELETE, or UP
16870 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20  DATE statement. 
16880 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72   Rows that.** ar
16890 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64  e changed as sid
168a0 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45  e effects of [RE
168b0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
168c0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
168d0 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
168e0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52   processing, [DR
168f0 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79  OP TABLE], or by
16900 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
16910 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
16920 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
16930 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a  row changes.)^.*
16940 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
16950 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
16960 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
16970 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
16980 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
16990 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43  e script of a [C
169a0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
169b0 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f  trigger]. .** Mo
169c0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
169d0 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
169e0 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
169f0 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
16a00 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
16a10 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
16a20 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
16a30 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
16a40 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
16a50 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
16a60 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
16a70 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
16a80 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
16a90 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
16aa0 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
16ab0 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
16ac0 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
16ad0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
16ae0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
16af0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
16b00 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
16b10 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
16b20 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
16b30 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
16b40 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
16b50 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
16b60 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
16b70 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
16b80 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
16b90 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
16ba0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
16bb0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
16bc0 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
16bd0 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
16be0 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  us, when called 
16bf0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
16c00 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
16c10 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
16c20 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
16c30 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
16c40 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
16c50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
16c60 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
16c70 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
16c80 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69   level.  ^(Withi
16c90 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
16ca0 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
16cb0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
16cc0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
16cd0 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
16ce0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
16cf0 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
16d00 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
16d10 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
16d20 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
16d30 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
16d40 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
16d50 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
16d60 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
16d70 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
16d80 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
16d90 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
16da0 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
16db0 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
16dc0 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
16dd0 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a  wn context.)^.**
16de0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
16df0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
16e00 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
16e10 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
16e20 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
16e30 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
16e40 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
16e50 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
16e60 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
16e70 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
16e80 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
16e90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
16ea0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
16eb0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
16ec0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
16ed0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
16ee0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
16ef0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
16f00 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
16f10 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
16f20 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
16f30 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
16f40 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
16f50 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
16f60 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
16f70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
16f80 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
16f90 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52  caused by [INSER
16fa0 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20  T],.** [UPDATE] 
16fb0 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
16fc0 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
16fd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16fe0 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
16ff0 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e  d..** ^(The coun
17000 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  t returned by sq
17010 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17020 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61  ges() includes a
17030 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72  ll changes.** fr
17040 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54  om all [CREATE T
17050 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
17060 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63  ] contexts and c
17070 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a  hanges made by.*
17080 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
17090 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72  ctions]. However
170a0 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64  ,.** the count d
170b0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
170c0 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20  changes used to 
170d0 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41  implement [REPLA
170e0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  CE] constraints,
170f0 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
17100 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
17110 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54  sing, or [DROP T
17120 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67  ABLE] processing
17130 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20  .  The.** count 
17140 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17150 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74   rows of views t
17160 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53  hat fire an [INS
17170 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
17180 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74  ,.** though if t
17190 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  he INSTEAD OF tr
171a0 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e  igger makes chan
171b0 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20  ges of its own, 
171c0 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a  those changes .*
171d0 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e  * are counted.)^
171e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
171f0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
17200 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73   function counts
17210 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20   the changes as 
17220 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73  soon as.** the s
17230 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
17240 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70  kes them is comp
17250 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
17260 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
17270 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f  .** is passed to
17280 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
17290 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
172a0 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
172b0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
172c0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
172d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
172e0 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
172f0 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
17300 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
17310 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
17320 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
17330 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
17340 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
17350 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
17360 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
17370 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
17380 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
17390 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
173a0 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
173b0 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
173c0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
173d0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
173e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
173f0 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
17400 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17410 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
17420 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
17430 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
17440 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
17450 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
17460 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
17470 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
17480 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
17490 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
174a0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
174b0 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
174c0 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
174d0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
174e0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
174f0 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
17500 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
17510 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
17520 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
17530 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
17540 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
17550 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
17560 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
17570 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
17580 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
17590 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
175a0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
175b0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
175c0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
175d0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
175e0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
175f0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
17600 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
17610 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
17620 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
17630 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
17640 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
17650 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
17660 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
17670 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
17680 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
17690 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
176a0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
176b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
176c0 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
176d0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
176e0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
176f0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
17700 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
17710 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
17720 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
17730 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
17740 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
17750 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
17760 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
17770 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
17780 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
17790 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
177a0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
177b0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
177c0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
177d0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
177e0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
177f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
17800 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
17810 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
17820 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
17830 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17840 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
17850 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
17860 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
17870 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
17880 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
17890 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
178a0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
178b0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
178c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
178d0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
178e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
178f0 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
17900 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
17910 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
17920 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
17930 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
17940 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
17950 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
17960 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
17970 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
17980 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
17990 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
179a0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
179b0 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
179c0 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
179d0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
179e0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
179f0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
17a00 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
17a10 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
17a20 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
17a30 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
17a40 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
17a50 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
17a60 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
17a70 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
17a80 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
17a90 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
17aa0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
17ab0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17ac0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
17ad0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
17ae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17af0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
17b00 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
17b10 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
17b20 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
17b30 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
17b40 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
17b50 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17b60 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
17b70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
17b80 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
17b90 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
17ba0 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
17bb0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
17bc0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
17bd0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
17be0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
17bf0 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
17c00 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
17c10 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
17c20 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
17c30 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
17c40 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
17c50 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
17c60 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
17c70 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
17c80 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
17c90 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
17ca0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
17cb0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
17cc0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
17cd0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
17ce0 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
17cf0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
17d00 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
17d10 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
17d20 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
17d30 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
17d40 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
17d50 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
17d60 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
17d70 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
17d80 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
17d90 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
17da0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
17db0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
17dc0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
17dd0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
17de0 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
17df0 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
17e00 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
17e10 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
17e20 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
17e30 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
17e40 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
17e50 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
17e60 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
17e70 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
17e80 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
17e90 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
17ea0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
17eb0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
17ec0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
17ed0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
17ee0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
17ef0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
17f00 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
17f10 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
17f20 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
17f30 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
17f40 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
17f50 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
17f60 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
17f70 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
17f80 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
17f90 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
17fa0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
17fb0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
17fc0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
17fd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
17fe0 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
17ff0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
18000 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
18010 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
18020 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
18030 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
18040 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
18050 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
18060 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
18070 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
18080 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
18090 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
180a0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
180b0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
180c0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
180d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
180e0 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
180f0 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
18100 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
18110 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
18120 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
18130 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
18140 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
18150 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
18160 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18170 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
18180 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
18190 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
181a0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
181b0 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
181c0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
181d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
181e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
181f0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
18200 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
18210 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
18220 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
18230 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
18240 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
18250 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
18260 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
18270 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
18280 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
18290 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
182a0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
182b0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
182c0 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
182d0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
182e0 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
182f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
18300 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
18310 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
18320 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
18330 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
18340 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
18350 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
18360 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
18370 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
18380 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
18390 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
183a0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
183b0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
183c0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
183d0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
183e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
183f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
18400 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
18410 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
18420 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
18430 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
18440 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
18450 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
18460 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
18470 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
18480 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
18490 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
184a0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
184b0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
184c0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
184d0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
184e0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
184f0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
18500 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
18510 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
18520 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
18530 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
18540 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
18550 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
18560 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
18570 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
18580 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
18590 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
185a0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
185b0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
185c0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
185d0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
185e0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
185f0 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
18600 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
18610 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
18620 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
18630 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
18640 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
18650 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
18660 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
18670 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
18680 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
18690 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
186a0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
186b0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
186c0 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
186d0 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
186e0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
186f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
18700 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
18710 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
18720 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
18730 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
18740 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
18750 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
18760 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
18770 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
18780 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
18790 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
187a0 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
187b0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
187c0 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
187d0 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
187e0 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
187f0 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
18800 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
18810 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
18820 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
18830 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
18840 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
18850 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
18860 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
18870 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
18880 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
18890 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
188a0 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
188b0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
188c0 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
188d0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
188e0 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
188f0 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
18900 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
18910 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
18920 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
18930 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
18940 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
18950 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
18960 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
18970 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
18980 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
18990 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
189a0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
189b0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
189c0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
189d0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
189e0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
189f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
18a00 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
18a10 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
18a20 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
18a30 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
18a40 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
18a50 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
18a60 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
18a70 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
18a80 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
18a90 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
18aa0 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
18ab0 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
18ac0 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
18ad0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
18ae0 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
18af0 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
18b00 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
18b10 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
18b20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
18b30 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
18b40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
18b50 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
18b60 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
18b70 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
18b80 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
18b90 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
18ba0 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
18bb0 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
18bc0 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
18bd0 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
18be0 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
18bf0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
18c00 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
18c10 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
18c20 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
18c30 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
18c40 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
18c50 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
18c60 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
18c70 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
18c80 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
18c90 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
18ca0 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
18cb0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
18cc0 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
18cd0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
18ce0 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
18cf0 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
18d00 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
18d10 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
18d20 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
18d30 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
18d40 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
18d50 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
18d60 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
18d70 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
18d80 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
18d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18da0 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
18db0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
18dc0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
18dd0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
18de0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
18df0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
18e00 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
18e10 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
18e20 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
18e30 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18e40 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
18e50 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
18e60 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
18e70 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
18e80 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
18e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
18ea0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
18eb0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
18ec0 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
18ed0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
18ee0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
18ef0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
18f00 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
18f10 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
18f20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18f30 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
18f40 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
18f50 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
18f60 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
18f70 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18f80 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
18f90 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
18fa0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
18fb0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
18fc0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a  Busy Timeout.**.
18fd0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
18fe0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
18ff0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
19000 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
19010 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
19020 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
19030 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
19040 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
19050 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
19060 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
19070 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
19080 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
19090 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
190a0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
190b0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
190c0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
190d0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
190e0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
190f0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
19100 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
19110 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
19120 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
19130 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
19140 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
19150 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
19160 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
19170 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
19180 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
19190 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
191a0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
191b0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
191c0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
191d0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
191e0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
191f0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
19200 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
19210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19220 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
19230 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
19240 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
19250 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
19260 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
19270 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
19280 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
19290 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
192a0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
192b0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
192c0 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73  ared.)^.*/.int s
192d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
192e0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
192f0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
19300 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
19310 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
19320 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
19330 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
19340 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
19350 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
19360 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
19370 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
19380 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
19390 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
193a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
193b0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
193c0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
193d0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
193e0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
193f0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
19400 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
19410 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
19420 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
19430 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
19440 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
19450 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
19460 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
19470 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
19480 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
19490 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
194a0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
194b0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
194c0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
194d0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
194e0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
194f0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
19500 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
19510 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
19520 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
19530 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
19540 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
19550 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
19560 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
19570 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
19580 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
19590 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
195a0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
195b0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
195c0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
195d0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
195e0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
195f0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
19600 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
19610 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
19620 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
19630 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
19640 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
19650 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
19660 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
19670 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
19680 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
19690 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
196a0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
196b0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
196c0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
196d0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
196e0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
196f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
19700 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
19710 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
19720 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
19730 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
19740 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
19750 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
19760 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
19770 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
19780 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
19790 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
197a0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
197b0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
197c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
197d0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
197e0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
197f0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
19800 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
19810 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
19820 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
19830 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
19840 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19850 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
19860 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
19870 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
19880 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
19890 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
198a0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
198b0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
198c0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
198d0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
198e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
198f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
19900 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
19910 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
19920 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
19930 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
19940 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
19950 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
19960 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
19970 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
19980 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
19990 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
199a0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
199b0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
199c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
199d0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
199e0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
199f0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
19a00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19a10 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
19a20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19a30 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
19a40 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
19a50 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
19a60 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
19a70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
19a80 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
19a90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19aa0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
19ab0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19ac0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
19ad0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19ae0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
19af0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
19b00 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
19b10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
19b20 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
19b30 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
19b40 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
19b50 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
19b60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
19b70 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
19b80 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
19b90 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
19ba0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
19bb0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
19bc0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
19bd0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
19be0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
19bf0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
19c00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19c10 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
19c20 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
19c30 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
19c40 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
19c50 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
19c60 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
19c70 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
19c80 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
19c90 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
19ca0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
19cb0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
19cc0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
19cd0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19ce0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
19cf0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
19d00 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
19d10 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
19d20 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
19d30 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
19d40 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
19d50 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
19d60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
19d70 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
19d80 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
19d90 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
19da0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
19db0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
19dc0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
19dd0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
19de0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
19df0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
19e00 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
19e10 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19e20 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
19e30 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
19e40 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
19e50 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
19e60 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
19e70 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
19e80 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
19e90 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
19ea0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
19eb0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
19ec0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
19ed0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
19ee0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
19ef0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
19f00 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
19f10 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
19f20 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
19f30 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
19f40 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
19f50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
19f60 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
19f70 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
19f80 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
19f90 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
19fa0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
19fb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
19fc0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
19fd0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
19fe0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
19ff0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1a000 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1a010 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1a020 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1a030 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1a040 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1a050 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1a060 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1a070 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1a080 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1a090 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1a0a0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1a0b0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1a0c0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1a0d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1a0e0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1a0f0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1a100 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1a110 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1a120 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1a130 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1a140 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1a150 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1a160 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1a170 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1a180 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1a190 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1a1a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1a1b0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1a1c0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1a1d0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1a1e0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1a1f0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1a200 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1a210 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1a220 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1a230 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1a240 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1a250 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1a260 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1a270 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1a280 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1a290 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1a2a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1a2b0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1a2c0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1a2d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1a2e0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1a2f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1a300 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1a310 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1a320 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1a330 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1a340 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1a350 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1a360 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1a370 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1a380 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1a390 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1a3a0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1a3b0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1a3c0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1a3d0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1a3e0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1a3f0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1a400 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1a410 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1a420 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1a430 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1a440 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1a450 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1a460 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1a470 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1a480 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1a490 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1a4a0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1a4b0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1a4c0 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1a4d0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1a4e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1a4f0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1a500 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1a510 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1a520 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1a530 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1a540 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1a550 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1a560 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1a570 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1a580 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1a590 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1a5a0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1a5b0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1a5c0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1a5d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1a5e0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1a5f0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1a600 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1a610 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1a620 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1a630 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1a640 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1a650 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a660 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1a670 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1a680 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1a690 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1a6a0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1a6b0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1a6c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1a6d0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1a6e0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1a6f0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1a700 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1a710 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1a720 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a730 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1a740 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1a750 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1a760 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1a770 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1a780 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1a790 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1a7a0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1a7b0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1a7c0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1a7d0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1a7e0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1a7f0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1a800 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1a810 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1a820 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1a830 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1a840 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1a850 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1a860 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1a870 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1a880 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1a890 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1a8a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1a8b0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1a8c0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1a8d0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1a8e0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1a8f0 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1a900 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1a910 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1a920 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1a930 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1a940 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1a950 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1a960 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1a970 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1a980 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1a990 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1a9a0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1a9b0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1a9c0 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1a9d0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1a9e0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1a9f0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1aa00 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1aa10 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1aa20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1aa30 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1aa40 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1aa50 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1aa60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1aa70 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1aa80 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1aa90 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1aaa0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1aab0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1aac0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1aad0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1aae0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1aaf0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1ab00 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1ab10 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1ab20 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ab30 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1ab40 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1ab50 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1ab60 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1ab70 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1ab80 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1ab90 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1aba0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1abb0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1abc0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1abd0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1abe0 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1abf0 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1ac00 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1ac10 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1ac20 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1ac30 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1ac40 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1ac50 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1ac60 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1ac70 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1ac80 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1ac90 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1aca0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1acb0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1acc0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1acd0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1ace0 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1acf0 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1ad00 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1ad10 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1ad20 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1ad30 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1ad40 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1ad50 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1ad60 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1ad70 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1ad80 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1ad90 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1ada0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1adb0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1adc0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1add0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1ade0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1adf0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1ae00 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1ae10 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1ae20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1ae30 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1ae40 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1ae50 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1ae60 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1ae70 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1ae80 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1ae90 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1aea0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1aeb0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1aec0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1aed0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1aee0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1aef0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1af00 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1af10 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1af20 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1af30 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1af40 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1af50 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1af60 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1af70 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1af80 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1af90 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1afa0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1afb0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1afc0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1afd0 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1afe0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1aff0 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1b000 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1b010 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1b020 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1b030 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1b040 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1b050 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b060 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1b070 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1b080 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1b090 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1b0a0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1b0b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1b0c0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1b0d0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1b0e0 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1b0f0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1b100 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1b110 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1b120 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1b130 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1b140 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1b150 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1b160 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1b170 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1b180 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1b190 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1b1a0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1b1b0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1b1c0 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1b1d0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1b1e0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1b1f0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1b200 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1b210 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1b220 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1b230 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1b240 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1b250 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1b260 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1b270 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1b280 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1b290 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1b2a0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1b2b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1b2c0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1b2d0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1b2e0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1b2f0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1b300 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1b310 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1b320 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1b330 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1b340 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1b350 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1b360 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1b370 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1b380 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1b390 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1b3a0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1b3b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1b3c0 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1b3d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1b3e0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1b3f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1b400 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1b410 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1b420 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1b430 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1b440 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1b450 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1b460 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1b470 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1b480 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1b490 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1b4a0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1b4b0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1b4c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1b4d0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1b4e0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1b4f0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1b500 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1b510 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1b520 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1b530 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1b540 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1b550 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1b560 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1b570 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1b580 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1b590 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1b5a0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1b5b0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1b5c0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1b5d0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1b5e0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1b5f0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1b600 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1b610 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1b620 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1b630 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1b640 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1b650 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1b660 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1b670 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1b680 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
1b690 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
1b6a0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1b6b0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1b6c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1b6d0 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
1b6e0 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
1b6f0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
1b700 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1b710 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
1b720 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
1b730 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
1b740 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
1b750 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
1b760 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b770 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1b780 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1b790 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1b7a0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1b7b0 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1b7c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1b7d0 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
1b7e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b7f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1b800 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
1b810 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1b820 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1b830 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
1b840 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1b850 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1b860 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1b870 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1b880 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1b890 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
1b8a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b8b0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1b8c0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
1b8d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1b8e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1b8f0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1b900 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1b910 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1b920 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1b930 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
1b940 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
1b950 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1b960 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1b970 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1b980 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1b990 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1b9a0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1b9b0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1b9c0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1b9d0 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1b9e0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1b9f0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
1ba00 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1ba10 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1ba20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1ba30 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
1ba40 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
1ba50 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
1ba60 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1ba70 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1ba80 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1ba90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
1baa0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1bab0 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
1bac0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1bad0 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1bae0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1baf0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1bb00 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1bb10 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1bb20 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1bb30 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1bb40 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1bb50 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1bb60 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1bb70 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1bb80 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1bb90 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1bba0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1bbb0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1bbc0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1bbd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1bbe0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1bbf0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1bc00 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1bc10 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1bc20 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1bc30 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1bc40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1bc50 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1bc60 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1bc70 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1bc80 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1bc90 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1bca0 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1bcb0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1bcc0 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1bcd0 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1bce0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1bcf0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1bd00 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1bd10 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1bd20 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1bd30 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1bd40 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1bd50 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1bd60 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1bd70 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1bd80 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1bd90 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1bda0 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1bdb0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1bdc0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1bdd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1bde0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1bdf0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1be00 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1be10 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1be20 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1be30 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1be40 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1be50 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1be60 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1be70 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1be80 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1be90 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1bea0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1beb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1bec0 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1bed0 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1bee0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1bef0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1bf00 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1bf10 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1bf20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1bf30 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1bf40 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1bf50 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1bf60 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1bf70 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1bf80 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1bf90 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
1bfa0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1bfb0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
1bfc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1bfd0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1bfe0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1bff0 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1c000 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1c010 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1c020 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1c030 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1c040 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1c050 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1c060 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1c070 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1c080 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1c090 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1c0a0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1c0b0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1c0c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1c0d0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1c0e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1c0f0 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1c100 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1c110 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1c120 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1c130 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1c140 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1c150 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1c160 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1c170 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1c180 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1c190 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1c1a0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1c1b0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1c1c0 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1c1d0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1c1e0 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1c1f0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1c200 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1c210 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1c220 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1c230 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1c240 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1c250 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1c260 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1c270 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1c280 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1c290 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1c2a0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1c2b0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1c2c0 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1c2d0 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1c2e0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1c2f0 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1c300 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1c310 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1c320 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1c330 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1c340 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1c350 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1c360 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1c370 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1c380 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1c390 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1c3a0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1c3b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1c3c0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1c3d0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1c3e0 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1c3f0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1c400 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1c410 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1c420 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1c430 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1c440 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1c450 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1c460 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1c470 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1c480 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1c490 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1c4a0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1c4b0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1c4c0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1c4d0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1c4e0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1c4f0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1c500 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1c510 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1c520 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1c530 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1c540 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1c550 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1c560 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1c570 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1c580 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1c590 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1c5a0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1c5b0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1c5c0 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1c5d0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1c5e0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1c5f0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1c600 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1c610 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1c620 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1c630 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1c640 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1c650 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1c660 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
1c670 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
1c680 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
1c690 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
1c6a0 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
1c6b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
1c6c0 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
1c6d0 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1c6e0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
1c6f0 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1c700 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
1c710 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1c720 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1c730 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
1c740 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
1c750 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
1c760 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1c770 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1c780 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1c790 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1c7a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1c7b0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1c7c0 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
1c7d0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1c7e0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1c7f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c800 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1c810 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1c820 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1c830 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1c840 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1c850 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1c860 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1c870 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c880 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1c890 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1c8a0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1c8b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c8c0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1c8d0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1c8e0 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1c8f0 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1c900 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1c910 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1c920 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c930 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1c940 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1c950 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1c960 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1c970 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1c980 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1c990 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1c9a0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1c9b0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1c9c0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1c9d0 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1c9e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c9f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1ca00 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1ca10 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1ca20 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1ca30 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ca40 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1ca50 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1ca60 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1ca70 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1ca80 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1ca90 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1caa0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1cab0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1cac0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1cad0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1cae0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1caf0 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1cb00 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1cb10 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1cb20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1cb30 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1cb40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1cb50 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1cb60 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1cb70 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1cb80 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1cb90 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1cba0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1cbb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cbc0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1cbd0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1cbe0 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1cbf0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1cc00 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1cc10 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1cc20 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1cc30 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1cc40 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1cc50 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1cc60 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1cc70 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1cc80 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1cc90 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1cca0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1ccb0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1ccc0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1ccd0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1cce0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1ccf0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1cd00 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1cd10 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1cd20 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1cd30 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1cd40 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1cd50 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1cd60 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1cd70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1cd80 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1cd90 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1cda0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1cdb0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1cdc0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1cdd0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1cde0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1cdf0 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1ce00 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1ce10 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1ce20 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1ce30 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1ce40 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1ce50 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1ce60 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1ce70 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1ce80 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1ce90 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1cea0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1ceb0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1cec0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1ced0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1cee0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1cef0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1cf00 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1cf10 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1cf20 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1cf30 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1cf40 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1cf50 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1cf60 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1cf70 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
1cf80 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
1cf90 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
1cfa0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1cfb0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
1cfc0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
1cfd0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
1cfe0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
1cff0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
1d000 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
1d010 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
1d020 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
1d030 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
1d040 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
1d050 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
1d060 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1d070 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1d080 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
1d090 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d0a0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
1d0b0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
1d0c0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
1d0d0 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
1d0e0 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
1d0f0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
1d100 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
1d110 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
1d120 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
1d130 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
1d140 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
1d150 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1d160 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
1d170 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1d180 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
1d190 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
1d1a0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
1d1b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1d1c0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
1d1d0 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
1d1e0 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
1d1f0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
1d200 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
1d210 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
1d220 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
1d230 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
1d240 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
1d250 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
1d260 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
1d270 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
1d280 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
1d290 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
1d2a0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
1d2b0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
1d2c0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
1d2d0 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
1d2e0 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
1d2f0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
1d300 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
1d310 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
1d320 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
1d330 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
1d340 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
1d350 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
1d360 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
1d370 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
1d380 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1d390 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
1d3a0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
1d3b0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
1d3c0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1d3d0 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
1d3e0 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
1d3f0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
1d400 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
1d410 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
1d420 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
1d430 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
1d440 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1d450 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
1d460 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
1d470 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
1d480 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1d490 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
1d4a0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
1d4b0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
1d4c0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
1d4d0 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
1d4e0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
1d4f0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
1d500 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
1d510 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
1d520 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
1d530 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
1d540 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
1d550 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
1d560 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
1d570 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
1d580 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
1d590 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
1d5a0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
1d5b0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1d5c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
1d5d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d5e0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1d5f0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1d600 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1d610 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d620 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1d630 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d640 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
1d650 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1d660 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1d670 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d680 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1d690 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1d6a0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1d6b0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1d6c0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1d6d0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
1d6e0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
1d6f0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
1d700 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
1d710 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
1d720 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
1d730 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
1d740 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
1d750 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
1d760 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
1d770 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
1d780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
1d790 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
1d7a0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
1d7b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d7c0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
1d7d0 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
1d7e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d7f0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
1d800 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
1d810 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1d820 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
1d830 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
1d840 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1d850 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
1d860 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
1d870 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
1d880 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
1d890 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
1d8a0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
1d8b0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
1d8c0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
1d8d0 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
1d8e0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
1d8f0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
1d900 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
1d910 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
1d920 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
1d930 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
1d940 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1d950 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1d960 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1d970 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1d980 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1d990 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1d9a0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1d9b0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1d9c0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1d9d0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1d9e0 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1d9f0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1da00 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1da10 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1da20 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1da30 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1da40 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1da50 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1da60 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1da70 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1da80 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1da90 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1daa0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1dab0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1dac0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1dad0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1dae0 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1daf0 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1db00 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1db10 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1db20 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1db30 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1db40 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f   as a [SQLITE_RO
1db50 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20  LLBACK | return 
1db60 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68  code].** from th
1db70 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
1db80 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
1db90 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
1dba0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
1dbb0 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
1dbc0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1dbd0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
1dbe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dbf0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
1dc00 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
1dc10 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
1dc20 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
1dc30 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1dc40 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
1dc50 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
1dc60 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1dc70 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1dc80 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
1dc90 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
1dca0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
1dcb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
1dcc0 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
1dcd0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1dce0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
1dcf0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1dd00 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1dd10 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
1dd20 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
1dd30 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
1dd40 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
1dd50 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
1dd60 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
1dd70 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
1dd80 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1dd90 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
1dda0 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
1ddb0 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
1ddc0 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
1ddd0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
1dde0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
1ddf0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
1de00 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1de10 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1de20 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
1de30 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1de40 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
1de50 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
1de60 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1de70 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
1de80 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
1de90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1dea0 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
1deb0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1dec0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1ded0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1dee0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1def0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
1df00 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
1df10 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
1df20 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
1df30 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1df40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1df50 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1df60 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1df70 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1df80 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1df90 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1dfa0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1dfb0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1dfc0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1dfd0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1dfe0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1dff0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
1e000 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e010 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e020 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
1e030 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
1e040 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
1e050 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
1e060 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
1e070 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1e080 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e090 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e0a0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
1e0b0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
1e0c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e0d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e0e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e0f0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1e100 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
1e110 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1e120 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e130 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e140 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1e150 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
1e160 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e170 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e190 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1e1a0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
1e1b0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1e1c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e1d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e1e0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
1e1f0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
1e200 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1e210 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e220 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e230 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
1e240 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
1e250 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1e260 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e280 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
1e290 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
1e2a0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1e2b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e2c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e2d0 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
1e2e0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
1e2f0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e300 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e320 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
1e330 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
1e340 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1e350 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e370 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
1e380 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
1e390 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e3a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e3b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e3c0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1e3d0 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
1e3e0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1e3f0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e400 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e410 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
1e420 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
1e430 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e440 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e450 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1e460 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
1e470 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
1e480 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1e490 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e4a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1e4b0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
1e4c0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1e4d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e4e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e4f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
1e500 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
1e510 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1e520 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1e530 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e540 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
1e550 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
1e560 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1e570 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e580 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e590 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
1e5a0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
1e5b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e5c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e5d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e5e0 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
1e5f0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
1e600 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
1e610 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
1e620 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
1e630 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
1e640 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
1e650 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e660 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1e670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e680 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
1e690 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
1e6a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e6b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e6c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e6d0 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
1e6e0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
1e6f0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
1e700 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e720 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
1e730 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
1e740 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1e750 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1e760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e770 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
1e780 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
1e790 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
1e7a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e7b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e7c0 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
1e7d0 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
1e7e0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
1e7f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
1e810 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
1e820 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
1e830 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
1e840 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
1e860 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
1e870 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
1e880 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e890 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e8a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
1e8b0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
1e8c0 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
1e8d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1e8e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e8f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e900 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
1e910 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
1e920 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1e930 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1e940 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1e950 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
1e960 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1e970 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1e980 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1e990 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
1e9a0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
1e9b0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1e9c0 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
1e9d0 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
1e9e0 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
1e9f0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
1ea00 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1ea10 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
1ea20 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
1ea30 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
1ea40 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
1ea50 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
1ea60 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
1ea70 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1ea80 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1ea90 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1eaa0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1eab0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1eac0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1ead0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1eae0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1eaf0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1eb00 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1eb10 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1eb20 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1eb30 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1eb40 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1eb50 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1eb60 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1eb70 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1eb80 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1eb90 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1eba0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1ebb0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1ebc0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1ebd0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1ebe0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1ebf0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1ec00 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1ec10 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1ec20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1ec30 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1ec40 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1ec50 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1ec60 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1ec70 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1ec80 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1ec90 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1eca0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1ecb0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1ecc0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1ecd0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1ece0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1ecf0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
1ed00 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
1ed10 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1ed20 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
1ed30 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
1ed40 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
1ed50 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
1ed60 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
1ed70 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
1ed80 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
1ed90 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1eda0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1edb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1edc0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1edd0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1ede0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1edf0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1ee00 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1ee10 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1ee20 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1ee30 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1ee40 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1ee50 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1ee60 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1ee70 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1ee80 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1ee90 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1eea0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1eeb0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1eec0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1eed0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1eee0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1eef0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1ef00 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1ef10 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1ef20 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1ef30 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1ef40 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1ef50 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1ef60 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1ef70 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1ef80 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1ef90 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1efa0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1efb0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1efc0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1efd0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1efe0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1eff0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1f000 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1f010 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1f020 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1f030 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1f040 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1f050 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1f060 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1f070 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1f080 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1f090 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1f0a0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1f0b0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1f0c0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1f0d0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1f0e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f0f0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1f100 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1f110 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1f120 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1f130 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1f140 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1f150 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1f160 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1f170 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1f180 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1f190 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1f1a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1f1b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f1c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1f1d0 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1f1e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f1f0 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1f200 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1f210 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1f220 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1f230 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1f240 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1f250 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1f260 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1f270 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1f280 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1f290 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1f2a0 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1f2b0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1f2c0 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
1f2d0 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
1f2e0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1f2f0 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
1f300 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
1f310 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
1f320 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
1f330 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
1f340 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  ck X..**.** ^Onl
1f350 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
1f360 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
1f370 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
1f380 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
1f390 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f3a0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
1f3b0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
1f3c0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
1f3d0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
1f3e0 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
1f3f0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
1f400 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
1f410 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
1f420 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1f430 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
1f440 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
1f450 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
1f460 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
1f470 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
1f480 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1f490 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1f4a0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
1f4b0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
1f4c0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
1f4d0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
1f4e0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
1f4f0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
1f500 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
1f510 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
1f520 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f530 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1f540 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1f550 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1f560 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1f570 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1f580 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
1f590 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1f5a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1f5b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f5c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1f5d0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1f5e0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1f5f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f600 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1f610 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1f620 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1f630 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
1f640 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1f650 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
1f660 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
1f670 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
1f680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
1f690 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
1f6a0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
1f6b0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1f6c0 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
1f6d0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
1f6e0 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
1f6f0 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
1f700 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
1f710 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1f720 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
1f730 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
1f740 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1f750 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1f760 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
1f770 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1f780 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
1f790 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
1f7a0 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
1f7b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f7c0 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
1f7d0 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
1f7e0 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
1f7f0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
1f800 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
1f810 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
1f820 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
1f830 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f840 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
1f850 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
1f860 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
1f870 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
1f880 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
1f890 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
1f8a0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1f8b0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
1f8c0 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
1f8d0 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
1f8e0 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
1f8f0 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
1f900 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
1f910 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
1f920 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1f930 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1f940 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
1f950 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1f960 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1f970 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
1f980 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1f990 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
1f9a0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
1f9b0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
1f9c0 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
1f9d0 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
1f9e0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
1f9f0 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
1fa00 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
1fa10 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
1fa20 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
1fa30 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  e will be UTF-8 
1fa40 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  if.** sqlite3_op
1fa50 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1fa60 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c  open_v2() is cal
1fa70 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31  led and.** UTF-1
1fa80 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1fa90 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71  byte order if sq
1faa0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69  lite3_open16() i
1fab0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68  s used..**.** Wh
1fac0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
1fad0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
1fae0 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
1faf0 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
1fb00 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1fb10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1fb20 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
1fb30 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
1fb40 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
1fb50 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
1fb60 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
1fb70 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
1fb80 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
1fb90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1fba0 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
1fbb0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
1fbc0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
1fbd0 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
1fbe0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
1fbf0 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
1fc00 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
1fc10 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
1fc20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1fc30 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
1fc40 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
1fc50 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
1fc60 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
1fc70 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
1fc80 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
1fc90 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
1fca0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
1fcb0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
1fcc0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
1fcd0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1fce0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1fcf0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
1fd00 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1fd10 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
1fd20 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
1fd30 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
1fd40 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
1fd50 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1fd60 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
1fd70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1fd80 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
1fd90 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
1fda0 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
1fdb0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
1fdc0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
1fdd0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1fde0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1fdf0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1fe00 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
1fe10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1fe20 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1fe30 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1fe40 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
1fe50 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
1fe60 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
1fe70 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
1fe80 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
1fe90 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1fea0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
1feb0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
1fec0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
1fed0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
1fee0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1fef0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1ff00 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1ff10 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1ff20 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
1ff30 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
1ff40 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1ff50 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1ff60 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1ff70 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
1ff80 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
1ff90 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
1ffa0 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
1ffb0 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
1ffc0 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
1ffd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1ffe0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1fff0 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
20000 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
20010 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
20020 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
20030 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
20040 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
20050 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
20060 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
20070 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
20080 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
20090 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
200a0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
200b0 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
200c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
200d0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
200e0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
200f0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
20100 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
20110 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20120 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
20130 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
20140 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
20150 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
20160 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
20170 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
20180 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
20190 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
201a0 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
201b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
201c0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
201d0 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
201e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
201f0 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
20200 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
20210 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
20220 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
20230 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
20240 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
20250 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
20260 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
20270 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
20280 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
20290 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
202a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
202b0 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
202c0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
202d0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
202e0 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
202f0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
20300 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
20310 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
20320 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
20330 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
20340 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
20350 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20360 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
20370 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
20380 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
20390 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
203a0 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
203b0 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
203c0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
203d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
203e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
203f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20400 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
20410 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
20420 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
20430 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
20440 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
20450 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
20460 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
20470 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
20480 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
20490 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
204a0 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
204b0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
204c0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
204d0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
204e0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
204f0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
20500 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
20510 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
20520 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
20530 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
20540 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
20550 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
20560 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
20570 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
20580 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
20590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
205a0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
205b0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
205c0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
205d0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
205e0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
205f0 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
20600 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
20610 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
20620 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
20630 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
20640 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
20650 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
20660 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
20670 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
20680 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
20690 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
206a0 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
206b0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
206c0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
206d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
206e0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
206f0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
20700 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
20710 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
20720 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
20730 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
20740 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
20750 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
20760 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
20770 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
20780 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20790 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
207a0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
207b0 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
207c0 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
207d0 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
207e0 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
207f0 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
20800 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
20810 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
20820 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
20830 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
20840 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
20850 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
20860 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
20870 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
20880 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
20890 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
208a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
208b0 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
208c0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
208d0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
208e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
208f0 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
20900 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
20910 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
20920 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
20930 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
20940 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
20950 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
20960 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
20970 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
20980 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
20990 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
209a0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
209b0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
209c0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
209d0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
209e0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
209f0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
20a00 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
20a10 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
20a20 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
20a30 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
20a40 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
20a50 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
20a60 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
20a70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
20a80 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
20a90 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
20aa0 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
20ab0 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
20ac0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
20ad0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
20ae0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
20af0 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
20b00 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
20b10 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
20b20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
20b30 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
20b40 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
20b50 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
20b60 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
20b70 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
20b80 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
20b90 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
20ba0 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
20bb0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
20bc0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
20bd0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
20be0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
20bf0 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
20c00 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
20c10 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
20c20 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
20c30 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
20c40 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
20c50 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
20c60 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
20c70 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
20c80 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
20c90 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
20ca0 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
20cb0 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
20cc0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
20cd0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
20ce0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
20cf0 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
20d00 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
20d10 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
20d20 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
20d30 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
20d40 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
20d50 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
20d60 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
20d70 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a   (e.g. "C:")..**
20d80 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
20d90 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
20da0 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
20db0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
20dc0 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
20dd0 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
20de0 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
20df0 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
20e00 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
20e10 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
20e20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
20e30 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  on]..** SQLite i
20e40 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f  nterprets the fo
20e50 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75  llowing three qu
20e60 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
20e70 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
20e80 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
20e90 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
20ea0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
20eb0 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
20ec0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
20ed0 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
20ee0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
20ef0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
20f00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
20f10 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
20f20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
20f30 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
20f40 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
20f50 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
20f60 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
20f70 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
20f80 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
20f90 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
20fa0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
20fb0 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
20fc0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
20fd0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20fe0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
20ff0 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
21000 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
21010 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
21020 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
21030 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
21040 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
21050 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
21060 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
21070 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
21080 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
21090 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
210a0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
210b0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
210c0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
210d0 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
210e0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
210f0 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
21100 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
21110 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
21120 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
21130 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
21140 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
21150 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
21160 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21170 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
21180 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
21190 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
211a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
211b0 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
211c0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
211d0 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
211e0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
211f0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
21200 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
21210 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
21220 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
21230 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
21240 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
21250 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
21260 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
21270 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
21280 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
21290 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
212a0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
212b0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
212c0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
212d0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
212e0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
212f0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
21300 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
21310 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
21320 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
21330 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
21340 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
21350 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
21360 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
21370 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
21380 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
21390 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
213a0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
213b0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
213c0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
213d0 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
213e0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
213f0 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
21400 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
21410 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
21420 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
21430 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
21440 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
21450 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
21460 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
21470 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
21480 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
21490 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
214a0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
214b0 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
214c0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
214d0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
214e0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
214f0 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
21500 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
21510 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
21520 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
21530 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
21540 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
21550 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
21560 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
21570 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
21580 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
21590 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
215a0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
215b0 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
215c0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
215d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
215e0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
215f0 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
21600 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
21610 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
21620 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
21630 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
21640 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
21650 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
21660 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
21670 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
21680 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
21690 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20  DCACHE flag..** 
216a0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
216b0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
216c0 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
216d0 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
216e0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
216f0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
21700 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
21710 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
21720 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
21730 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
21740 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
21750 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
21760 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
21770 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
21780 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
21790 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
217a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
217b0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
217c0 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
217d0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
217e0 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
217f0 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
21800 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
21810 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
21820 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
21830 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
21840 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
21850 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
21860 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
21870 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
21880 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
21890 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
218a0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
218b0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
218c0 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
218d0 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
218e0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
218f0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
21900 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
21910 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
21920 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
21930 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
21940 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
21950 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21960 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
21970 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
21980 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21990 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
219a0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
219b0 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
219c0 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
219d0 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
219e0 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
219f0 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
21a00 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
21a10 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
21a20 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
21a30 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
21a40 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
21a50 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
21a60 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
21a70 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
21a80 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
21a90 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
21aa0 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
21ab0 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
21ac0 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
21ad0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
21ae0 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
21af0 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
21b00 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
21b10 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
21b20 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
21b30 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
21b40 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
21b50 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
21b60 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
21b70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
21b80 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
21b90 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
21ba0 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
21bb0 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
21bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
21bd0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
21be0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
21bf0 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
21c00 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
21c10 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
21c20 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
21c30 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
21c40 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
21c50 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
21c60 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20  nolock <td>.**  
21c70 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
21c80 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
21c90 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
21ca0 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
21cb0 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74  x-nolock"..** <t
21cc0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
21cd0 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
21ce0 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
21cf0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
21d00 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
21d10 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
21d20 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
21d30 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
21d40 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
21d50 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
21d60 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
21d70 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
21d80 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
21d90 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
21da0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
21db0 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
21dc0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
21dd0 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
21de0 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
21df0 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
21e00 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
21e10 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
21e20 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
21e30 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
21e40 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
21e50 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
21e60 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
21e70 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
21e80 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
21e90 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
21ea0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
21eb0 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
21ec0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
21ed0 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
21ee0 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
21ef0 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
21f00 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
21f10 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
21f20 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
21f30 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
21f40 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
21f50 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
21f60 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
21f70 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
21f80 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
21f90 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
21fa0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
21fb0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
21fc0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
21fd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21fe0 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
21ff0 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
22000 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
22010 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
22020 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
22030 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
22040 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
22050 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
22060 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
22070 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
22080 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
22090 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
220a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
220b0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
220c0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
220d0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
220e0 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
220f0 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
22100 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
22110 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
22120 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
22130 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
22140 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
22150 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
22160 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
22170 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
22180 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
22190 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
221a0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
221b0 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
221c0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
221d0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
221e0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
221f0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
22200 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
22210 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
22220 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
22230 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
22240 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
22250 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
22260 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
22270 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
22280 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
22290 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
222a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
222b0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
222c0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
222d0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
222e0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
222f0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
22300 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
22310 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
22320 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
22330 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
22340 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
22350 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
22360 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
22370 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
22380 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
22390 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
223a0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
223b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
223c0 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
223d0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
223e0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
223f0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
22400 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
22410 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
22420 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
22430 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
22440 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
22450 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
22460 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
22470 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
22480 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
22490 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
224a0 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
224b0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
224c0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
224d0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
224e0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
224f0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
22500 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
22510 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
22520 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
22530 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
22540 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
22550 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
22560 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
22570 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
22580 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
22590 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
225a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
225b0 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
225c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
225d0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
225e0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
225f0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
22600 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
22610 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
22620 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
22630 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
22640 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
22650 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
22660 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
22670 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
22680 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
22690 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
226a0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
226b0 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
226c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
226d0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
226e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
226f0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
22700 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
22710 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
22720 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
22730 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
22740 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
22750 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
22760 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
22770 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
22780 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
22790 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
227a0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
227b0 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
227c0 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
227d0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
227e0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
227f0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
22800 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
22810 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
22820 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
22830 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
22840 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22850 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
22860 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
22870 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
22880 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
22890 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
228a0 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
228b0 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
228c0 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
228d0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
228e0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
228f0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
22900 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
22910 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
22920 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
22930 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
22940 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
22950 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
22960 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22970 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
22980 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
22990 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
229a0 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
229b0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
229c0 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
229d0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
229e0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
229f0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
22a00 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
22a10 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
22a20 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
22a30 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
22a40 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
22a50 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
22a60 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
22a70 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
22a80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
22a90 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
22aa0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
22ab0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
22ac0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
22ad0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
22ae0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
22af0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
22b00 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
22b10 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
22b20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
22b30 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
22b40 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
22b50 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
22b60 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
22b70 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
22b80 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
22b90 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
22ba0 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
22bb0 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
22bc0 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
22bd0 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
22be0 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
22bf0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
22c00 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
22c10 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
22c20 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
22c30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
22c40 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
22c50 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
22c60 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
22c70 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
22c80 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
22c90 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
22ca0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
22cb0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
22cc0 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
22cd0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
22ce0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
22cf0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
22d00 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
22d10 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
22d20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
22d30 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
22d40 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
22d50 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
22d60 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
22d70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22d80 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
22d90 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
22da0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
22db0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
22dc0 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
22dd0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
22de0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
22df0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
22e00 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
22e10 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
22e20 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
22e30 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
22e40 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
22e50 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
22e60 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
22e70 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
22e80 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
22e90 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
22ea0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
22eb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22ec0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
22ed0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
22ee0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
22ef0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
22f00 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
22f10 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
22f20 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
22f30 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
22f40 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
22f50 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
22f60 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
22f70 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
22f80 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
22f90 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
22fa0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
22fb0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
22fc0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
22fd0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
22fe0 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
22ff0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
23000 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
23010 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
23020 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
23030 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
23040 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
23050 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
23060 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
23070 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
23080 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
23090 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
230a0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
230b0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
230c0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
230d0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
230e0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
230f0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
23100 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
23110 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
23120 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
23130 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
23140 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
23150 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
23160 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
23170 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
23180 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
23190 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
231a0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
231b0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
231c0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
231d0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
231e0 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
231f0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
23200 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
23210 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
23220 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
23230 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
23240 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
23250 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
23260 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
23270 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
23280 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
23290 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
232a0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
232b0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
232c0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
232d0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
232e0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
232f0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
23300 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
23310 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
23320 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
23330 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
23340 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
23350 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
23360 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
23370 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
23380 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
23390 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
233a0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
233b0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
233c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
233d0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
233e0 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
233f0 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
23400 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
23410 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
23420 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
23430 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
23440 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
23450 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
23460 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
23470 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
23480 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
23490 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
234a0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
234b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
234c0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
234d0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
234e0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
234f0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63  lite3*);.const c
23500 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
23510 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
23520 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
23530 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
23540 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
23550 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23560 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
23570 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
23580 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
23590 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
235a0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
235b0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
235c0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
235d0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
235e0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
235f0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
23600 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
23610 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
23620 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
23630 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
23640 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
23650 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
23660 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
23670 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
23680 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
23690 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
236a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
236b0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
236c0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
236d0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
236e0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
236f0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
23700 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
23710 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
23720 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
23730 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
23740 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
23750 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
23760 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
23770 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
23780 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
23790 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
237a0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
237b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
237c0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
237d0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
237e0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
237f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
23800 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
23810 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
23820 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
23830 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
23840 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
23850 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
23860 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
23870 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
23880 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
23890 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
238a0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
238b0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
238c0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
238d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
238e0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
238f0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
23900 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
23910 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
23920 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
23930 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
23940 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
23950 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
23960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
23970 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
23980 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
23990 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
239a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
239b0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
239c0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
239d0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
239e0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
239f0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
23a00 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
23a10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
23a20 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
23a30 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
23a40 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
23a50 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
23a60 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
23a70 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
23a80 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
23a90 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
23aa0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
23ab0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
23ac0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
23ad0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
23ae0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
23af0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
23b00 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
23b10 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
23b20 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
23b30 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
23b40 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
23b50 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
23b60 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
23b70 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
23b80 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
23b90 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
23ba0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
23bb0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
23bc0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
23bd0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
23be0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
23bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
23c00 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
23c10 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
23c20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
23c30 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
23c40 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
23c50 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
23c60 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
23c70 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
23c80 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
23c90 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
23ca0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
23cb0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
23cc0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
23cd0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
23ce0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
23cf0 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
23d00 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
23d10 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
23d20 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
23d30 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
23d40 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
23d50 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
23d60 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
23d70 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
23d80 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
23d90 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
23da0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
23db0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
23dc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
23dd0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
23de0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
23df0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
23e00 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
23e10 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
23e20 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
23e30 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
23e40 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
23e50 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
23e60 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
23e70 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
23e80 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
23e90 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
23ea0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
23eb0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
23ec0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
23ed0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
23ee0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
23ef0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
23f00 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
23f10 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
23f20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
23f30 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
23f40 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
23f50 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
23f60 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23f70 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
23f80 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
23f90 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
23fa0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
23fb0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
23fc0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
23fd0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
23fe0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
23ff0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
24000 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
24010 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
24020 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
24030 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
24040 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
24050 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
24060 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24070 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
24080 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
24090 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
240a0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
240b0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
240c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
240d0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
240e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
240f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
24100 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
24110 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
24120 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
24130 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
24140 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
24150 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
24160 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
24170 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
24180 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
24190 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
241a0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
241b0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
241c0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
241d0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
241e0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
241f0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
24200 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24210 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
24220 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
24230 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
24240 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
24250 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
24260 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
24270 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
24280 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
24290 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
242a0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
242b0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
242c0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
242d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
242e0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
242f0 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
24300 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24310 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
24320 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
24330 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
24340 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24350 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
24360 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
24370 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
24380 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
24390 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
243a0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
243b0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
243c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
243d0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
243e0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
243f0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
24400 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
24410 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
24420 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
24430 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
24440 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
24450 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
24460 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
24470 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
24480 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
24490 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
244a0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
244b0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
244c0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
244d0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
244e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
244f0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
24500 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
24510 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
24520 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24530 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
24540 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
24550 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
24560 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24570 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
24580 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
24590 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
245a0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
245b0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
245c0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
245d0 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
245e0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
245f0 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
24600 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
24610 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
24620 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
24630 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
24640 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
24650 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
24660 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
24670 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
24680 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
24690 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
246a0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
246b0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
246c0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
246d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
246e0 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
246f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
24700 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
24710 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24720 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
24730 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
24740 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
24750 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24760 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
24770 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
24780 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24790 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
247a0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
247b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
247c0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
247d0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
247e0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
247f0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
24800 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
24810 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
24820 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
24830 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
24840 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
24850 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
24860 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
24870 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
24880 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
24890 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
248a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
248b0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
248c0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
248d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
248e0 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
248f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24900 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
24910 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
24920 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
24930 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
24940 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
24950 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
24960 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
24970 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
24980 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
24990 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
249a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
249b0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
249c0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
249d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
249e0 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
249f0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
24a00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
24a10 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
24a20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
24a30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24a40 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
24a50 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
24a60 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24a70 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
24a80 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
24a90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24aa0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
24ab0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
24ac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24ad0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
24ae0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
24af0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24b00 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
24b10 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
24b20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24b30 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
24b40 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
24b50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24b60 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
24b70 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
24b80 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
24b90 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
24ba0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
24bb0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
24bc0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
24bd0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
24be0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
24bf0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
24c00 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
24c10 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
24c20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
24c30 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
24c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24c50 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
24c60 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
24c70 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
24c80 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
24c90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24ca0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
24cb0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
24cc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24cd0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
24ce0 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
24cf0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
24d00 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
24d10 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
24d20 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
24d30 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
24d40 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
24d50 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
24d60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
24d70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
24d80 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
24d90 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
24da0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
24db0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
24dc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24dd0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
24de0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
24df0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
24e00 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
24e10 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
24e20 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
24e30 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
24e40 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
24e50 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
24e60 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
24e70 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
24e80 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
24e90 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
24ea0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
24eb0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
24ec0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
24ed0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
24ee0 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
24ef0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
24f00 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
24f10 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
24f20 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
24f30 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
24f40 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
24f50 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
24f60 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
24f70 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
24f80 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
24f90 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
24fa0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
24fb0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
24fc0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
24fd0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
24fe0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
24ff0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
25000 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
25010 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
25020 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
25030 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
25040 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
25050 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
25060 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
25070 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
25080 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
25090 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
250a0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
250b0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
250c0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
250d0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
250e0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
250f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
25100 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
25110 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
25120 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
25130 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
25140 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
25150 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
25160 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
25170 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
25180 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
25190 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
251a0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
251b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
251c0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
251d0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
251e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
251f0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
25200 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
25210 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
25220 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
25230 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
25240 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
25250 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
25260 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
25270 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
25280 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
25290 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
252a0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
252b0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
252c0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
252d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
252e0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
252f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
25300 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
25310 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
25320 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
25330 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
25340 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
25350 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
25360 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
25370 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
25380 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
25390 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
253a0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
253b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
253c0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
253d0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
253e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
253f0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
25400 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
25410 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
25420 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
25430 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
25440 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
25450 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
25460 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
25470 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
25480 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
25490 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
254a0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
254b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
254c0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
254d0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
254e0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
254f0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
25500 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
25510 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
25520 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
25530 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
25540 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
25550 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
25560 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
25570 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
25580 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
25590 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
255a0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
255b0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
255c0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
255d0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
255e0 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
255f0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
25600 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
25610 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
25620 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
25630 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
25640 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
25650 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
25660 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
25670 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
25680 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
25690 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
256a0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
256b0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
256c0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
256d0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
256e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
256f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
25700 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
25710 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
25720 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
25730 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
25740 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
25750 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
25760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25770 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
25780 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
25790 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
257a0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
257b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
257c0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
257d0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
257e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
257f0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
25800 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
25810 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
25820 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
25830 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
25840 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
25850 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
25860 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
25870 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
25880 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
25890 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
258a0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
258b0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
258c0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
258d0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
258e0 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
258f0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
25900 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
25910 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
25920 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
25930 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
25940 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
25950 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
25960 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
25970 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
25980 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
25990 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
259a0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
259b0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
259c0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
259d0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
259e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
259f0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
25a00 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
25a10 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
25a20 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
25a30 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
25a40 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
25a50 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
25a60 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
25a70 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
25a80 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
25a90 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
25aa0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
25ab0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
25ac0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
25ad0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
25ae0 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
25af0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
25b00 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
25b10 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
25b20 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
25b30 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
25b40 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
25b50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
25b60 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
25b70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
25b80 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
25b90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
25ba0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
25bb0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
25bc0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
25bd0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
25be0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
25bf0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
25c00 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
25c10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
25c20 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
25c30 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
25c40 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
25c50 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
25c60 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
25c70 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
25c80 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
25c90 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
25ca0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
25cb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25cc0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25cd0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
25ce0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
25cf0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
25d00 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
25d10 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
25d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
25d30 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
25d40 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
25d50 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
25d60 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
25d70 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
25d80 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25d90 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
25da0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
25db0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
25dc0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
25dd0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
25de0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
25df0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
25e00 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
25e10 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
25e20 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
25e30 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
25e40 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
25e50 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
25e60 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
25e70 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
25e80 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
25e90 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
25ea0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
25eb0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
25ec0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
25ed0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
25ee0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
25ef0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
25f00 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
25f10 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
25f20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25f30 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
25f40 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
25f50 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
25f60 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
25f70 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
25f80 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
25f90 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
25fa0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
25fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
25fc0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
25fd0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
25fe0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
25ff0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
26000 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
26010 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26020 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
26030 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
26040 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
26050 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
26060 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
26070 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
26080 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
26090 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
260a0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
260b0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
260c0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
260d0 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
260e0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
260f0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
26100 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
26110 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
26120 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
26130 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
26140 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
26150 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
26160 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
26170 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
26180 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
26190 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
261a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
261b0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
261c0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
261d0 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
261e0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
261f0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
26200 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
26210 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
26220 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
26230 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
26240 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26250 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
26260 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
26270 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
26280 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
26290 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
262a0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
262b0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
262c0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
262d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
262e0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
262f0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
26300 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
26310 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
26320 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
26330 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
26340 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
26350 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
26360 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
26370 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
26380 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
26390 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
263a0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
263b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
263c0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
263d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
263e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
263f0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
26400 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
26410 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
26420 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
26430 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
26440 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
26450 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
26460 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
26470 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
26480 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
26490 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
264a0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
264b0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
264c0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
264d0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
264e0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
264f0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
26500 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
26510 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
26520 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
26530 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
26540 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
26550 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
26560 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
26570 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
26580 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
26590 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
265a0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
265b0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
265c0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
265d0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
265e0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
265f0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
26600 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
26610 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
26620 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
26630 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
26640 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
26650 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
26660 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
26670 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
26680 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
26690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
266a0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
266b0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
266c0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
266d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
266e0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
266f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
26700 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
26710 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
26720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26730 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
26740 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
26750 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
26760 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
26770 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
26780 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
26790 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
267a0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
267b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
267c0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
267d0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
267e0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
267f0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
26800 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
26810 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
26820 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
26830 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
26840 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
26850 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
26860 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
26870 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
26880 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
26890 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
268a0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
268b0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
268c0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
268d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
268e0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
268f0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
26900 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
26910 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
26920 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
26930 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
26940 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
26950 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
26960 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
26970 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
26980 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
26990 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
269a0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
269b0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
269c0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
269d0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
269e0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
269f0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
26a00 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
26a10 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
26a20 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
26a30 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
26a40 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
26a50 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
26a60 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
26a70 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
26a80 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
26a90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
26aa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26ab0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
26ac0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
26ad0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
26ae0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26af0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
26b00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26b10 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
26b20 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
26b30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
26b40 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
26b50 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
26b60 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
26b70 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
26b80 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
26b90 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
26ba0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
26bb0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
26bc0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
26bd0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26be0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
26bf0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
26c00 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
26c10 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
26c20 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
26c30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26c40 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
26c50 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
26c60 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
26c70 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
26c80 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
26c90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26ca0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
26cb0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
26cc0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
26cd0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
26ce0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
26cf0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
26d00 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
26d10 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
26d20 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
26d30 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
26d40 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
26d50 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
26d60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26d70 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
26d80 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
26d90 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
26da0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
26db0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
26dc0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
26dd0 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
26de0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
26df0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
26e00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26e10 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
26e20 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
26e30 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
26e40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26e50 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
26e60 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
26e70 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
26e80 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
26e90 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
26ea0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
26eb0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
26ec0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
26ed0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
26ee0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
26ef0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
26f00 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
26f10 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
26f20 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
26f30 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
26f40 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
26f50 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
26f60 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
26f70 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
26f80 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
26f90 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
26fa0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
26fb0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
26fc0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
26fd0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
26fe0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
26ff0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
27000 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
27010 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
27020 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
27030 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
27040 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
27050 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
27060 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
27070 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
27080 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
27090 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
270a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
270b0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
270c0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
270d0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
270e0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
270f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
27100 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
27110 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
27120 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
27130 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
27140 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
27150 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
27160 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
27170 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
27180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27190 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
271a0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
271b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
271c0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
271d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
271e0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
271f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
27200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
27210 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
27220 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
27230 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
27240 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27250 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
27260 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
27270 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
27280 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
27290 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
272a0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
272b0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
272c0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
272d0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
272e0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
272f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
27300 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
27310 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
27320 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
27330 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
27340 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
27350 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
27360 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
27370 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
27380 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27390 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
273a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
273b0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
273c0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
273d0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
273e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
273f0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
27400 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
27410 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27420 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
27430 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
27440 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
27450 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
27460 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
27470 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
27480 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
27490 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
274a0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
274b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
274c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
274d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
274e0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
274f0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
27500 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
27510 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
27520 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
27530 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
27540 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
27550 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
27560 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
27570 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
27580 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
27590 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
275a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
275b0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
275c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
275d0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
275e0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
275f0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
27600 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
27610 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
27620 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
27630 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
27640 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
27650 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
27660 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
27670 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
27680 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
27690 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
276a0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
276b0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
276c0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
276d0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
276e0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
276f0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
27700 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
27710 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
27720 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
27730 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
27740 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
27750 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
27760 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
27770 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
27780 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
27790 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
277a0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
277b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
277c0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
277d0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
277e0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
277f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
27800 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
27810 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
27820 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
27830 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
27840 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
27850 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
27860 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
27870 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
27880 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
27890 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
278a0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
278b0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
278c0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
278d0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
278e0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
278f0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
27900 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
27910 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
27920 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
27930 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
27940 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
27950 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
27960 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
27970 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
27980 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
27990 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
279a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
279b0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
279c0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
279d0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
279e0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
279f0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
27a00 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
27a10 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
27a20 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
27a30 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
27a40 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
27a50 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
27a60 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
27a70 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
27a80 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
27a90 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
27aa0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
27ab0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
27ac0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
27ad0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
27ae0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
27af0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
27b00 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
27b10 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
27b20 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
27b30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
27b40 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
27b50 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
27b60 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
27b70 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
27b80 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
27b90 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
27ba0 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
27bb0 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
27bc0 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
27bd0 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
27be0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
27bf0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
27c00 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
27c10 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
27c20 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
27c30 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
27c40 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
27c50 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
27c60 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
27c70 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
27c80 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
27c90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27ca0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
27cb0 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
27cc0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
27cd0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
27ce0 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
27cf0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
27d00 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
27d10 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
27d20 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
27d30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27d40 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
27d50 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
27d60 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
27d70 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
27d80 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
27d90 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
27da0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
27db0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
27dc0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
27dd0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
27de0 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e  nd_text16() then
27df0 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
27e00 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
27e10 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
27e20 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
27e30 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
27e40 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
27e50 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
27e60 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
27e70 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
27e80 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
27e90 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
27ea0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
27eb0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
27ec0 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
27ed0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
27ee0 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
27ef0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
27f00 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
27f10 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
27f20 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
27f30 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
27f40 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
27f50 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
27f60 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
27f70 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
27f80 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
27f90 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
27fa0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
27fb0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
27fc0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
27fd0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
27fe0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
27ff0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
28000 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
28010 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
28020 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
28030 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
28040 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
28050 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
28060 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
28070 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
28080 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
28090 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
280a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
280b0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
280c0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
280d0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
280e0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
280f0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
28100 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
28110 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
28120 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
28130 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
28140 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
28150 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
28160 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
28170 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
28180 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
28190 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
281a0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
281b0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
281c0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
281d0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
281e0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
281f0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
28200 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
28210 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
28220 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
28230 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
28240 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
28250 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
28260 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
28270 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
28280 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
28290 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
282a0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
282b0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
282c0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
282d0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
282e0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
282f0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
28300 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
28310 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
28320 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
28330 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
28340 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
28350 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
28360 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
28370 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
28380 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
28390 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
283a0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
283b0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
283c0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
283d0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
283e0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
283f0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
28400 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
28410 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
28420 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28430 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
28440 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28450 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
28460 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28470 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
28480 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
28490 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
284a0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
284b0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
284c0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
284d0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
284e0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
284f0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
28500 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
28510 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
28520 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
28530 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
28540 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
28550 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
28560 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
28570 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
28580 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
28590 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
285a0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
285b0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
285c0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
285d0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
285e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
285f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
28600 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
28610 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
28620 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
28630 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
28640 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
28650 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
28660 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
28670 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
28680 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
28690 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
286a0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
286b0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
286c0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
286d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
286e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
286f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
28700 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
28710 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
28720 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28730 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
28740 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
28750 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
28760 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
28770 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
28780 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
28790 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
287a0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
287b0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
287c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
287d0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
287e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
287f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
28800 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
28810 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
28820 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
28830 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
28840 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
28850 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
28860 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
28870 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
28880 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
28890 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
288a0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
288b0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
288c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
288d0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
288e0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
288f0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
28900 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
28910 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28920 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
28930 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
28940 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
28950 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28960 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
28970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
28980 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
28990 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
289a0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
289b0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
289c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
289d0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
289e0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
289f0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
28a00 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
28a10 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
28a20 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
28a30 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
28a40 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
28a50 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
28a60 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
28a70 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
28a80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28a90 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
28aa0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
28ab0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
28ac0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
28ad0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
28ae0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
28af0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
28b00 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
28b10 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
28b20 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
28b30 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
28b40 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
28b50 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
28b60 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
28b70 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
28b80 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
28b90 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
28ba0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
28bb0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
28bc0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
28bd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28be0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
28bf0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
28c00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
28c10 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
28c20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28c30 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
28c40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
28c50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
28c60 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
28c70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
28c80 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
28c90 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
28ca0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28cb0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28cc0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
28cd0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
28ce0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
28cf0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
28d00 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
28d10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28d20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
28d30 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
28d40 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
28d50 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
28d60 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
28d70 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
28d80 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
28d90 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
28da0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
28db0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
28dc0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
28dd0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
28de0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
28df0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
28e00 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
28e10 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
28e20 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
28e30 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
28e40 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
28e50 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
28e60 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
28e70 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
28e80 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
28e90 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
28ea0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
28eb0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
28ec0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
28ed0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
28ee0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
28ef0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
28f00 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
28f10 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
28f20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
28f30 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
28f40 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
28f50 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
28f60 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
28f70 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
28f80 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
28f90 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
28fa0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
28fb0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
28fc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28fd0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
28fe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28ff0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
29000 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
29010 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
29020 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
29030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29040 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
29050 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
29060 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29070 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
29080 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29090 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
290a0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
290b0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
290c0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
290d0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
290e0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
290f0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
29100 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
29110 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
29120 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
29130 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
29140 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
29150 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
29160 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
29170 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
29180 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29190 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
291a0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
291b0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
291c0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
291d0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
291e0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
291f0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
29200 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
29210 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
29220 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
29230 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
29240 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
29250 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29260 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
29270 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29280 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29290 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
292a0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
292b0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
292c0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
292d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
292e0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
292f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29300 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
29310 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29320 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
29330 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
29340 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
29350 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
29360 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
29370 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
29380 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
29390 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
293a0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
293b0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
293c0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
293d0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
293e0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
293f0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
29400 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
29410 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
29420 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
29430 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
29440 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
29450 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
29460 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
29470 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
29480 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
29490 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
294a0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
294b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
294c0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
294d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
294e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
294f0 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
29500 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
29510 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
29520 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
29530 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
29540 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
29550 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
29560 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
29570 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
29580 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
29590 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
295a0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
295b0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
295c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
295d0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
295e0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
295f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
29600 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
29610 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
29620 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
29630 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
29640 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
29650 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
29660 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
29670 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
29680 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29690 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
296a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
296b0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
296c0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
296d0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
296e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
296f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
29700 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
29710 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
29720 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
29730 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29740 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
29750 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
29760 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
29770 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
29780 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
29790 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
297a0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
297b0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
297c0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
297d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
297e0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
297f0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
29800 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29810 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
29820 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
29830 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
29840 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
29850 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
29860 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
29870 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
29880 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29890 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
298a0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
298b0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
298c0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
298d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
298e0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
298f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
29900 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
29910 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
29920 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
29930 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
29940 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
29950 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
29960 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
29970 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
29980 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
29990 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
299a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
299b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
299c0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
299d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
299e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
299f0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
29a00 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
29a10 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
29a20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
29a30 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
29a40 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
29a50 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
29a60 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
29a70 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
29a80 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
29a90 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
29aa0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
29ab0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
29ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
29ad0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29ae0 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
29af0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
29b00 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
29b10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
29b20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29b30 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
29b40 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
29b50 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
29b60 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
29b70 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
29b80 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
29b90 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
29ba0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
29bb0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
29bc0 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
29bd0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
29be0 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
29bf0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
29c00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
29c10 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
29c20 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
29c30 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
29c40 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
29c50 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
29c60 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
29c70 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
29c80 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
29c90 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
29ca0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
29cb0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
29cc0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
29cd0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
29ce0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
29cf0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
29d00 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
29d10 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
29d20 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29d30 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
29d40 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
29d50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29d60 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
29d70 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
29d80 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
29d90 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
29da0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
29db0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
29dc0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
29dd0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
29de0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
29df0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
29e00 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
29e10 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
29e20 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
29e30 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
29e40 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
29e50 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
29e60 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
29e70 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
29e80 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
29e90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
29ea0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
29eb0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
29ec0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
29ed0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
29ee0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
29ef0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
29f00 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
29f10 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
29f20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
29f30 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
29f40 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
29f50 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
29f60 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
29f70 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
29f80 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
29f90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
29fa0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
29fb0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
29fc0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
29fd0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
29fe0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
29ff0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2a000 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2a010 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2a020 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2a030 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2a040 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2a050 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2a060 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2a070 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2a080 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2a090 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2a0a0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2a0b0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2a0c0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2a0d0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2a0e0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2a0f0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2a100 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2a110 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2a120 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2a130 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2a140 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2a150 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2a160 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2a170 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2a180 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2a190 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2a1a0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2a1b0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2a1c0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2a1d0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2a1e0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2a1f0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2a200 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2a210 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2a220 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2a230 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2a240 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2a250 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2a260 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a270 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2a280 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2a290 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2a2a0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2a2b0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2a2c0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2a2d0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2a2e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a2f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2a300 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2a310 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2a320 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2a330 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a340 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2a350 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2a360 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2a370 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2a380 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2a390 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a3a0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2a3b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2a3c0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2a3d0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2a3e0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2a3f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a400 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2a410 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a420 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2a430 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2a440 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2a450 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2a460 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2a470 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2a480 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a490 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2a4a0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2a4b0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2a4c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2a4d0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2a4e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a4f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a500 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2a510 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2a520 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2a530 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2a540 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2a550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2a560 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2a570 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2a580 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2a590 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2a5a0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2a5b0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2a5c0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2a5d0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2a5e0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2a5f0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2a600 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2a610 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2a620 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2a630 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2a640 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2a650 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2a660 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2a670 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2a680 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2a690 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2a6a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2a6b0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2a6c0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2a6d0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2a6e0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2a6f0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2a700 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2a710 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2a720 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2a730 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2a740 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2a750 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2a760 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2a770 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2a780 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2a790 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2a7a0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2a7b0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2a7c0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2a7d0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2a7e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2a7f0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2a800 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2a810 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2a820 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2a830 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2a840 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2a850 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2a860 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2a870 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2a880 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2a890 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2a8a0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2a8b0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2a8c0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2a8d0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2a8e0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2a8f0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2a900 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2a910 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2a920 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2a930 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2a940 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2a950 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2a960 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2a970 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2a980 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2a990 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2a9a0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2a9b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2a9c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2a9d0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2a9e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a9f0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2aa00 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2aa10 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2aa20 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2aa30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2aa40 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2aa50 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2aa60 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2aa70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2aa80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2aa90 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2aaa0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2aab0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2aac0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2aad0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2aae0 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2aaf0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2ab00 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2ab10 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2ab20 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2ab30 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2ab40 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2ab50 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2ab60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2ab70 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2ab80 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2ab90 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2aba0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2abb0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2abc0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2abd0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2abe0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2abf0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2ac00 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2ac10 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2ac20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ac30 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ac40 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2ac50 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2ac60 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2ac70 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2ac80 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2ac90 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2aca0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2acb0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2acc0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2acd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2ace0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2acf0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2ad00 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2ad10 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2ad20 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2ad30 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2ad40 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2ad50 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2ad60 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2ad70 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2ad80 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2ad90 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2ada0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2adb0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2adc0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2add0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2ade0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2adf0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2ae00 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2ae10 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2ae20 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2ae30 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2ae40 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2ae50 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2ae60 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2ae70 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2ae80 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2ae90 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2aea0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2aeb0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2aec0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2aed0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2aee0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2aef0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2af00 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2af10 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2af20 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2af30 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2af40 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2af50 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2af60 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2af70 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2af80 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2af90 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2afa0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2afb0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2afc0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2afd0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2afe0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2aff0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2b000 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2b010 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2b020 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2b030 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2b040 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2b050 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2b060 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2b070 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2b080 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2b090 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2b0a0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2b0b0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2b0c0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2b0d0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2b0e0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2b0f0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2b100 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2b110 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2b120 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2b130 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2b140 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2b150 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2b160 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2b170 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2b180 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2b190 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2b1a0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2b1b0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2b1c0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2b1d0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2b1e0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2b1f0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2b200 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2b210 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2b220 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2b230 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2b240 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2b250 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2b260 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2b270 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2b280 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2b290 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2b2a0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2b2b0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2b2c0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2b2d0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2b2e0 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2b2f0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2b300 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2b310 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2b320 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2b330 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2b340 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2b350 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2b360 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2b370 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2b380 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2b390 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2b3a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2b3b0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2b3c0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2b3d0 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2b3e0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2b3f0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2b400 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2b410 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2b420 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2b430 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2b440 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2b450 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2b460 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2b470 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2b480 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2b490 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2b4a0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2b4b0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2b4c0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2b4d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2b4e0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2b4f0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2b500 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2b510 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2b520 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2b530 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2b540 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2b550 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2b560 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2b570 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b580 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2b590 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2b5a0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2b5b0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2b5c0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2b5d0 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2b5e0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2b5f0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2b600 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2b610 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2b620 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b630 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2b640 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2b650 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2b660 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2b670 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2b680 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2b690 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2b6a0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2b6b0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2b6c0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2b6d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2b6e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2b6f0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2b700 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2b710 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2b720 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2b730 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2b740 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2b750 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2b760 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2b770 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2b780 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2b790 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2b7a0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2b7b0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2b7c0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2b7d0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2b7e0 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2b7f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2b800 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2b810 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2b820 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2b830 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2b840 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2b850 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2b860 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2b870 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2b880 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2b890 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2b8a0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2b8b0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2b8c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2b8d0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2b8e0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2b8f0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2b900 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2b910 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2b920 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2b930 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2b940 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2b950 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2b960 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2b970 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2b980 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2b990 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2b9a0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2b9b0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2b9c0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2b9d0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2b9e0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2b9f0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2ba00 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2ba10 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2ba20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ba30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2ba40 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2ba50 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2ba60 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2ba70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2ba80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ba90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2baa0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2bab0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2bac0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2bad0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2bae0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2baf0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2bb00 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2bb10 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2bb20 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2bb30 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2bb40 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2bb50 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2bb60 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2bb70 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2bb80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2bb90 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2bba0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2bbb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2bbc0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2bbd0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2bbe0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2bbf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bc00 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2bc10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2bc20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2bc30 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2bc40 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2bc50 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2bc60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2bc70 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2bc80 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2bc90 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2bca0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2bcb0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2bcc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2bcd0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2bce0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2bcf0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2bd00 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2bd10 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2bd20 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2bd30 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2bd40 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2bd50 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2bd60 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2bd70 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2bd80 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2bd90 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2bda0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2bdb0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2bdc0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2bdd0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2bde0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2bdf0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2be00 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2be10 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2be20 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2be30 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2be40 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2be50 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2be60 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2be70 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2be80 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2be90 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2bea0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2beb0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
2bec0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2bed0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2bee0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2bef0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2bf00 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2bf10 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2bf20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2bf30 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2bf40 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2bf50 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2bf60 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2bf70 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2bf80 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2bf90 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2bfa0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2bfb0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2bfc0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2bfd0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2bfe0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2bff0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2c000 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2c010 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2c020 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2c030 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2c040 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2c050 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2c060 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2c070 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2c080 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2c090 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2c0a0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2c0b0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2c0c0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2c0d0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2c0e0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2c0f0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2c100 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2c110 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2c120 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2c130 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2c140 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2c150 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2c160 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2c170 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2c180 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2c190 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2c1a0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2c1b0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2c1c0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2c1d0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2c1e0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2c1f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c200 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2c210 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2c220 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2c230 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2c240 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2c250 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2c260 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2c270 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2c280 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2c290 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2c2a0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2c2b0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2c2c0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2c2d0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2c2e0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2c2f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2c300 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2c310 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2c320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c330 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2c340 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2c350 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2c360 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2c370 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2c380 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2c390 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2c3a0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2c3b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2c3c0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2c3d0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2c3e0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2c3f0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2c400 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2c410 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2c420 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2c430 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2c440 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2c450 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2c460 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2c470 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2c480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2c490 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2c4a0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2c4b0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2c4c0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2c4d0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2c4e0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2c4f0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2c500 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2c510 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2c520 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2c530 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2c540 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2c550 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2c560 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2c570 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2c580 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2c590 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2c5a0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2c5b0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2c5c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c5d0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2c5e0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2c5f0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2c600 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2c610 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2c620 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2c630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2c640 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2c650 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2c660 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2c670 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2c680 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2c690 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2c6a0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2c6b0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2c6c0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2c6d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2c6e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c6f0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2c700 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2c710 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2c720 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2c730 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2c740 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2c750 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2c760 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2c770 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2c780 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2c790 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2c7a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2c7b0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2c7c0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2c7d0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2c7e0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2c7f0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2c800 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2c810 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2c820 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2c830 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2c840 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2c850 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2c860 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2c870 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2c880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c890 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2c8a0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2c8b0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2c8c0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2c8d0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2c8e0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2c8f0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2c900 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2c910 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2c920 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2c930 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2c940 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2c950 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2c960 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2c970 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2c980 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2c990 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2c9a0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2c9b0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2c9c0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2c9d0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2c9e0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2c9f0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2ca00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2ca10 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2ca20 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2ca30 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2ca40 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2ca50 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2ca60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ca70 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2ca80 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2ca90 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2caa0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2cab0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2cac0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2cad0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2cae0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2caf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2cb00 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2cb10 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2cb20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2cb30 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2cb40 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2cb50 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2cb60 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2cb70 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2cb80 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2cb90 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2cba0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2cbb0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2cbc0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2cbd0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2cbe0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2cbf0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2cc00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2cc10 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2cc20 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2cc30 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2cc40 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2cc50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2cc60 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2cc70 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2cc80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2cc90 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2cca0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2ccb0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2ccc0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2ccd0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2cce0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2ccf0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2cd00 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2cd10 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2cd20 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2cd30 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2cd40 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2cd50 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2cd60 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2cd70 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2cd80 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2cd90 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2cda0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2cdb0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2cdc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2cdd0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2cde0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2cdf0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ce00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ce10 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2ce20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ce30 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2ce40 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2ce50 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2ce60 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2ce70 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2ce80 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2ce90 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2cea0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2ceb0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2cec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ced0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2cee0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2cef0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2cf00 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2cf10 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2cf20 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2cf30 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2cf40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2cf50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2cf60 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2cf70 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2cf80 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2cf90 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2cfa0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2cfb0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2cfc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2cfd0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2cfe0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2cff0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2d000 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2d010 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2d020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2d030 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2d040 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2d050 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d060 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2d070 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2d080 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2d090 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2d0a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2d0b0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2d0c0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2d0d0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2d0e0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2d0f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2d100 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2d110 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d120 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2d130 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2d140 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2d150 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2d160 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2d170 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2d180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d190 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2d1a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2d1b0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2d1c0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2d1d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2d1e0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2d1f0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2d200 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2d210 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2d220 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2d230 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2d240 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2d250 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2d260 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2d270 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2d280 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2d290 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2d2a0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2d2b0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2d2c0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2d2d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2d2e0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2d2f0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2d300 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2d310 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2d320 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2d330 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2d340 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2d350 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2d360 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2d370 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2d380 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2d390 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2d3a0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2d3b0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2d3c0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2d3d0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2d3e0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2d3f0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2d400 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2d410 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2d420 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2d430 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2d440 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2d450 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2d460 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2d470 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2d480 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2d490 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2d4a0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2d4b0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2d4c0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2d4d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2d4e0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2d4f0 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2d500 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2d510 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2d520 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2d530 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2d540 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2d550 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2d560 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2d570 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
2d580 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
2d590 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
2d5a0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2d5b0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2d5c0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
2d5d0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2d5e0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2d5f0 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
2d600 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2d610 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2d620 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
2d630 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2d640 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2d650 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2d660 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
2d670 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2d680 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2d690 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2d6a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2d6b0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2d6c0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2d6d0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2d6e0 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2d6f0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2d700 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2d710 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2d720 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
2d730 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2d740 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2d750 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2d760 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2d770 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2d780 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2d790 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2d7a0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2d7b0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2d7c0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2d7d0 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2d7e0 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2d7f0 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2d800 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2d810 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2d820 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2d830 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2d840 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2d850 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2d860 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2d870 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2d880 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2d890 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2d8a0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2d8b0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2d8c0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2d8d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2d8e0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2d8f0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2d900 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2d910 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2d920 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2d930 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2d940 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2d950 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2d960 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2d970 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2d980 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2d990 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2d9a0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2d9b0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2d9c0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2d9d0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2d9e0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2d9f0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2da00 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2da10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2da20 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2da30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2da40 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2da50 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2da60 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2da70 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2da80 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2da90 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2daa0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2dab0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2dac0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2dad0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2dae0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2daf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2db00 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2db10 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2db20 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2db30 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2db40 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2db50 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2db60 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2db70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2db80 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2db90 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2dba0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2dbb0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2dbc0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2dbd0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2dbe0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2dbf0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2dc00 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2dc10 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2dc20 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2dc30 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2dc40 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2dc50 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2dc60 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2dc70 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2dc80 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2dc90 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2dca0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2dcb0 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2dcc0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2dcd0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2dce0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2dcf0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2dd00 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2dd10 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2dd20 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2dd30 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2dd40 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2dd50 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2dd60 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2dd70 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2dd80 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2dd90 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2dda0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2ddb0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2ddc0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2ddd0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2dde0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2ddf0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2de00 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2de10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2de20 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2de30 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2de40 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2de50 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2de60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2de70 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2de80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2de90 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2dea0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2deb0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2dec0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2ded0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2dee0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2def0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2df00 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2df10 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2df20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2df30 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2df40 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2df50 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2df60 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2df70 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2df80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2df90 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2dfa0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2dfb0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2dfc0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2dfd0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2dfe0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2dff0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e000 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2e010 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2e020 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2e030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e040 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2e050 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2e060 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e070 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2e080 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2e090 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2e0a0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2e0b0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2e0c0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2e0d0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2e0e0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2e0f0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2e100 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2e110 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2e120 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2e130 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2e140 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2e150 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2e160 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2e170 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2e180 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2e190 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2e1a0 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2e1b0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2e1c0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
2e1d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2e1e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
2e1f0 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
2e200 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
2e210 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2e220 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
2e230 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2e240 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2e250 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
2e260 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
2e270 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
2e280 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
2e290 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
2e2a0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
2e2b0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
2e2c0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
2e2d0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2e2e0 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
2e2f0 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
2e300 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2e310 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2e320 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
2e330 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2e340 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
2e350 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2e360 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2e370 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e380 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2e390 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2e3a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e3b0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2e3c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2e3d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e3e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
2e3f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2e400 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2e410 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2e420 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2e430 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
2e440 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e450 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2e460 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e470 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2e480 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2e490 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
2e4a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2e4b0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
2e4c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e4d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2e4e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e4f0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2e500 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2e510 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2e520 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
2e530 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e540 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
2e550 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2e560 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2e570 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
2e580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e590 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
2e5a0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2e5b0 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
2e5c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e5d0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2e5e0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
2e5f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e600 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
2e610 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2e620 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
2e630 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
2e640 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
2e650 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
2e660 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
2e670 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
2e680 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
2e690 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
2e6a0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
2e6b0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2e6c0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2e6d0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
2e6e0 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
2e6f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2e700 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
2e710 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2e720 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
2e730 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2e740 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
2e750 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2e760 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
2e770 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2e780 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
2e790 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
2e7a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e7b0 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
2e7c0 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
2e7d0 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
2e7e0 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
2e7f0 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
2e800 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e810 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
2e820 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
2e830 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
2e840 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2e850 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
2e860 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
2e870 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
2e880 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
2e890 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
2e8a0 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
2e8b0 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2e8c0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2e8d0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2e8e0 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
2e8f0 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
2e900 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
2e910 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
2e920 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
2e930 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
2e940 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
2e950 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2e960 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
2e970 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e980 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2e990 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
2e9a0 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
2e9b0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2e9c0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2e9d0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
2e9e0 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
2e9f0 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
2ea00 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
2ea10 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
2ea20 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
2ea30 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
2ea40 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
2ea50 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
2ea60 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2ea70 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2ea80 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2ea90 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2eaa0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2eab0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
2eac0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
2ead0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
2eae0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2eaf0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
2eb00 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
2eb10 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
2eb20 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
2eb30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
2eb40 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
2eb50 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
2eb60 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
2eb70 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2eb80 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2eb90 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
2eba0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
2ebb0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
2ebc0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2ebd0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2ebe0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
2ebf0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2ec00 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2ec10 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
2ec20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ec30 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
2ec40 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
2ec50 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
2ec60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2ec70 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2ec80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2ec90 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2eca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ecb0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2ecc0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2ecd0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
2ece0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2ecf0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2ed00 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2ed10 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
2ed20 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2ed30 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2ed40 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2ed50 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2ed60 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2ed70 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2ed80 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2ed90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2eda0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2edb0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
2edc0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2edd0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
2ede0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2edf0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
2ee00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2ee10 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2ee20 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2ee30 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
2ee40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ee50 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2ee60 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ee70 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2ee80 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2ee90 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2eea0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2eeb0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2eec0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2eed0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
2eee0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
2eef0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2ef00 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
2ef10 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2ef20 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2ef30 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
2ef40 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2ef50 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2ef60 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
2ef70 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
2ef80 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2ef90 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2efa0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2efb0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2efc0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2efd0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2efe0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2eff0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2f000 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2f010 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2f020 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2f030 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
2f040 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
2f050 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
2f060 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
2f070 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
2f080 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2f090 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
2f0a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
2f0b0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
2f0c0 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
2f0d0 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
2f0e0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2f0f0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
2f100 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2f110 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2f120 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2f130 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
2f140 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2f150 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
2f160 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
2f170 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
2f180 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
2f190 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
2f1a0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2f1b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
2f1c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f1d0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2f1e0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
2f1f0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
2f200 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2f210 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2f220 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
2f230 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2f240 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2f250 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2f260 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2f270 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
2f280 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
2f290 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
2f2a0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
2f2b0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
2f2c0 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
2f2d0 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
2f2e0 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
2f2f0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
2f300 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2f310 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
2f320 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
2f330 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
2f340 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
2f350 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
2f360 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
2f370 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
2f380 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
2f390 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
2f3a0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2f3b0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
2f3c0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
2f3d0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2f3e0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
2f3f0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2f400 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2f410 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
2f420 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
2f430 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
2f440 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2f450 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
2f460 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
2f470 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
2f480 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
2f490 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
2f4a0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2f4b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2f4c0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
2f4d0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
2f4e0 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
2f4f0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
2f500 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
2f510 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
2f520 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2f530 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
2f540 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
2f550 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
2f560 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
2f570 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
2f580 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
2f590 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
2f5a0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
2f5b0 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20  ers.  Every SQL 
2f5c0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2f5d0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
2f5e0 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
2f5f0 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
2f600 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
2f610 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
2f620 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
2f630 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
2f640 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
2f650 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
2f660 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
2f670 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
2f680 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2f690 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2f6a0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2f6b0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2f6c0 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2f6d0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2f6e0 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2f6f0 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2f700 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2f710 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
2f720 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2f730 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2f740 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2f750 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2f760 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2f770 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2f780 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2f790 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2f7a0 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2f7b0 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2f7c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2f7d0 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2f7e0 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2f7f0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2f800 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2f810 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2f820 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2f830 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
2f840 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2f850 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2f860 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2f870 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2f880 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2f890 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2f8a0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2f8b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2f8c0 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
2f8d0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
2f8e0 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
2f8f0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
2f900 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
2f910 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
2f920 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
2f930 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
2f940 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2f950 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2f960 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
2f970 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
2f980 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2f990 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2f9a0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
2f9b0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
2f9c0 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
2f9d0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2f9e0 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
2f9f0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
2fa00 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
2fa10 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2fa20 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2fa30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
2fa40 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
2fa50 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
2fa60 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
2fa70 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
2fa80 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
2fa90 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
2faa0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2fab0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
2fac0 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
2fad0 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
2fae0 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
2faf0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
2fb00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2fb10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fb20 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
2fb30 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
2fb40 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
2fb50 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2fb60 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2fb70 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
2fb80 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
2fb90 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
2fba0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
2fbb0 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
2fbc0 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
2fbd0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2fbe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
2fbf0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
2fc00 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
2fc10 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
2fc20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2fc30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2fc40 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
2fc50 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
2fc60 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2fc70 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
2fc80 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
2fc90 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
2fca0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
2fcb0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
2fcc0 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
2fcd0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
2fce0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
2fcf0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
2fd00 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2fd10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fd20 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
2fd30 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
2fd40 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
2fd50 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2fd60 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
2fd70 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
2fd80 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
2fd90 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
2fda0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
2fdb0 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
2fdc0 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
2fdd0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2fde0 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
2fdf0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
2fe00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2fe10 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
2fe20 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
2fe30 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
2fe40 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2fe50 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
2fe60 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2fe70 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
2fe80 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
2fe90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2fea0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
2feb0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
2fec0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
2fed0 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
2fee0 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
2fef0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
2ff00 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2ff10 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
2ff20 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
2ff30 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
2ff40 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
2ff50 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2ff60 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
2ff70 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
2ff80 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2ff90 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2ffa0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
2ffb0 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
2ffc0 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
2ffd0 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
2ffe0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2fff0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
30000 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
30010 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
30020 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
30030 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
30040 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
30050 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
30060 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30070 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
30080 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
30090 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
300a0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
300b0 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
300c0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
300d0 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
300e0 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
300f0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
30100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30110 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
30120 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
30130 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
30140 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
30150 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
30160 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
30170 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30180 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
30190 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
301a0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
301b0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
301c0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
301d0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
301e0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
301f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
30200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
30210 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
30220 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30230 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30240 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30250 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
30260 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
30270 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
30280 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
30290 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
302a0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
302b0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
302c0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
302d0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
302e0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
302f0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
30300 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
30310 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
30320 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
30330 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
30340 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
30350 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
30360 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
30370 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
30380 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30390 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
303a0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
303b0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
303c0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
303d0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
303e0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
303f0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
30400 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
30410 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
30420 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
30430 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
30440 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
30450 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
30460 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
30470 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
30480 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
30490 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
304a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
304b0 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
304c0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
304d0 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
304e0 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
304f0 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
30500 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
30510 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
30520 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
30530 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
30540 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
30550 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
30560 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
30570 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
30580 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
30590 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
305a0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
305b0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
305c0 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
305d0 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
305e0 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
305f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30600 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
30610 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
30620 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
30630 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
30640 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
30650 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
30660 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
30670 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
30680 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
30690 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
306a0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
306b0 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
306c0 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
306d0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
306e0 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
306f0 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
30700 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
30710 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
30720 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
30730 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
30740 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
30750 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
30760 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
30770 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
30780 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
30790 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
307a0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
307b0 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
307c0 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
307d0 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
307e0 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
307f0 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
30800 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
30810 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
30820 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
30830 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
30840 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
30850 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
30860 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
30870 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
30880 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
30890 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
308a0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
308b0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
308c0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
308d0 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
308e0 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
308f0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
30900 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
30910 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
30920 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
30930 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
30940 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
30950 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
30960 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a  te3_int64,int),.
30970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30980 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69        void*,sqli
30990 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
309a0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
309b0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
309c0 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
309d0 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
309e0 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
309f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30a00 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
30a10 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
30a20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
30a30 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
30a40 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
30a50 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
30a60 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
30a70 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
30a80 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
30a90 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
30aa0 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
30ab0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
30ac0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
30ad0 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
30ae0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30af0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
30b00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30b10 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
30b20 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
30b30 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
30b40 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
30b50 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
30b60 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
30b70 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
30b80 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
30b90 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
30ba0 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
30bb0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30bc0 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
30bd0 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
30be0 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
30bf0 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
30c00 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
30c10 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
30c20 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
30c30 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
30c40 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
30c50 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30c60 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
30c70 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
30c80 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
30c90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30ca0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
30cb0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
30cc0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
30cd0 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
30ce0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30cf0 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
30d00 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
30d10 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
30d20 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
30d30 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
30d40 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
30d50 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
30d60 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
30d70 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65  except that  the
30d80 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
30d90 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
30da0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30db0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
30dc0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
30dd0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
30de0 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
30df0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
30e00 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
30e10 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
30e20 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
30e30 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
30e40 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
30e50 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
30e60 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
30e70 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
30e80 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
30e90 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
30ea0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
30eb0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
30ec0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
30ed0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
30ee0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
30ef0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
30f00 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
30f10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
30f20 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
30f30 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
30f40 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
30f50 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
30f60 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
30f70 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
30f80 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
30f90 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
30fa0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
30fb0 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
30fc0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
30fd0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
30fe0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
30ff0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
31000 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
31010 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
31020 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
31030 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
31040 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
31050 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
31060 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
31070 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
31080 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
31090 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
310a0 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
310b0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
310c0 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
310d0 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
310e0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
310f0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
31100 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
31110 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
31120 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
31130 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
31140 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
31150 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
31160 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
31170 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
31180 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
31190 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
311a0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
311b0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
311c0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
311d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
311e0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
311f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
31200 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
31210 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
31220 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
31230 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
31240 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
31250 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
31260 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
31270 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
31280 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
31290 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
312a0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
312b0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
312c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
312d0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
312e0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
312f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
31300 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
31310 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
31320 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
31330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
31340 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
31350 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
31360 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
31370 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
31380 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
31390 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
313a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
313b0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
313c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
313d0 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
313e0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
313f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
31400 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
31410 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
31420 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
31430 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
31440 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
31450 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31460 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
31470 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31480 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
31490 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
314a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
314b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
314c0 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
314d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
314e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
314f0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
31500 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
31510 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
31520 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
31530 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
31540 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
31550 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
31560 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
31570 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
31580 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
31590 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
315a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
315b0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
315c0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
315d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
315e0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
315f0 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
31600 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
31610 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
31620 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
31630 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31640 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
31650 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
31660 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
31670 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
31680 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31690 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
316a0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
316b0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
316c0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
316d0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
316e0 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
316f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
31700 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
31710 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
31720 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
31730 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
31740 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
31750 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
31760 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
31770 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
31780 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
31790 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
317a0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
317b0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
317c0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
317d0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
317e0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
317f0 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
31800 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
31810 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
31820 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
31830 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
31840 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31850 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
31860 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
31870 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
31880 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
31890 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
318a0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
318b0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
318c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
318d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
318e0 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
318f0 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
31900 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
31910 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
31920 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
31930 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
31940 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
31950 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
31960 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
31970 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31980 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
31990 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
319a0 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
319b0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
319c0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
319d0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
319e0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
319f0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
31a00 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31a10 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
31a20 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
31a30 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
31a40 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
31a50 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
31a60 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
31a70 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
31a80 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
31a90 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
31aa0 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
31ab0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
31ac0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31ad0 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
31ae0 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
31af0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
31b00 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
31b10 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
31b20 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
31b30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
31b40 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
31b50 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31b60 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
31b70 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
31b80 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
31b90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
31ba0 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
31bb0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
31bc0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
31bd0 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
31be0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
31bf0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
31c00 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
31c10 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
31c20 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
31c30 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
31c40 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
31c50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
31c60 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
31c70 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
31c80 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
31c90 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
31ca0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
31cb0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
31cc0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
31cd0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31ce0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31cf0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
31d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31d10 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
31d20 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
31d30 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
31d40 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
31d50 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
31d60 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
31d70 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
31d80 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
31d90 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
31da0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
31db0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
31dc0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
31dd0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
31de0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31df0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
31e00 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
31e10 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
31e20 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
31e30 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
31e40 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
31e50 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
31e60 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
31e70 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
31e80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31e90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31ea0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
31eb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
31ec0 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
31ed0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
31ee0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
31ef0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
31f00 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
31f10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31f20 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
31f30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
31f40 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
31f50 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
31f60 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
31f70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
31f80 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
31f90 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
31fa0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31fb0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
31fc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31fd0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
31fe0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
31ff0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
32000 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
32010 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
32020 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
32030 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
32040 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
32050 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
32060 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
32070 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
32080 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Data.**.** The 
32090 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
320a0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
320b0 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
320c0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
320d0 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
320e0 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
320f0 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
32100 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
32110 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
32120 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
32130 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
32140 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
32150 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
32160 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
32170 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
32180 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
32190 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
321a0 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61  eserved. This ma
321b0 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f  y.** be used, fo
321c0 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64  r example, to ad
321d0 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  d a regular-expr
321e0 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20  ession matching 
321f0 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69  scalar.** functi
32200 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
32210 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
32220 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
32230 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a  on is stored as.
32240 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
32250 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
32260 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
32270 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
32280 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
32290 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
322a0 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
322b0 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
322c0 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
322d0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
322e0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
322f0 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
32300 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
32310 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
32320 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
32330 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
32340 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
32350 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32360 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
32370 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32380 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
32390 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
323a0 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
323b0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
323c0 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
323d0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
323e0 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
323f0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
32400 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32410 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61  ion. ^If no meta
32420 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
32430 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66  er.** been set f
32440 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  or the Nth argum
32450 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
32460 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
32470 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
32480 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
32490 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  er has changed s
324a0 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
324b0 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74  ta was set,.** t
324c0 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
324d0 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e  auxdata() return
324e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
324f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32500 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32510 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
32520 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  es the metadata.
32530 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
32540 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
32550 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61  er as the metada
32560 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
32570 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
32580 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32590 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
325a0 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
325b0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
325c0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
325d0 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
325e0 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
325f0 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
32600 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69  troyed..** ^If i
32610 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
32620 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
32630 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
32640 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
32650 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
32660 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
32670 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
32680 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
32690 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
326a0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
326b0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
326c0 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
326d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
326e0 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
326f0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
32700 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
32710 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
32720 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
32730 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
32740 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
32750 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
32760 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
32770 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67  me.  ^The only g
32780 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
32790 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
327a0 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
327b0 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
327c0 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
327d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
327e0 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
327f0 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
32800 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
32810 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
32820 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
32830 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
32840 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
32850 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
32860 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
32870 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a  arameters].)^.**
32880 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32890 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
328a0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
328b0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
328c0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
328d0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
328e0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
328f0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
32900 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
32910 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
32920 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32930 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32940 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
32950 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
32960 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
32970 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
32980 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
32990 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
329a0 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
329b0 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
329c0 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
329d0 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
329e0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
329f0 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
32a00 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
32a10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32a20 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74  _blob()].  ^If t
32a30 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
32a40 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
32a50 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
32a60 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
32a70 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
32a80 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
32a90 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
32aa0 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
32ab0 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
32ac0 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20  royed.  ^The.** 
32ad0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
32ae0 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
32af0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
32b00 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
32b10 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
32b20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
32b30 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
32b40 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
32b50 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
32b60 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
32b70 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
32b80 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
32b90 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
32ba0 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
32bb0 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
32bc0 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a   C++ compilers..
32bd0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
32be0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
32bf0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
32c00 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
32c10 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
32c20 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
32c30 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
32c40 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
32c50 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
32c60 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
32c70 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
32c80 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
32c90 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
32ca0 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
32cb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32cc0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
32cd0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
32ce0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
32cf0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
32d00 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
32d10 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
32d20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
32d30 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
32d40 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
32d50 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
32d60 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
32d70 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
32d80 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
32d90 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
32da0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
32db0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
32dc0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
32dd0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
32de0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
32df0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
32e00 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
32e10 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
32e20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
32e30 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
32e40 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
32e50 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
32e60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32e70 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
32e80 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
32e90 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
32ea0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
32eb0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32ec0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
32ed0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
32ee0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
32ef0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
32f00 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
32f10 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
32f20 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
32f30 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
32f40 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
32f50 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32f60 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
32f70 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
32f80 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
32f90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32fa0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
32fb0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
32fc0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
32fd0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
32fe0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
32ff0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
33000 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
33010 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
33020 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33030 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
33040 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
33050 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
33060 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33070 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
33080 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
33090 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
330a0 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
330b0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
330c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
330d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
330e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
330f0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
33100 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
33110 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
33120 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
33130 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
33140 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
33150 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
33160 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
33170 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
33180 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
33190 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
331a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
331b0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
331c0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
331d0 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
331e0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
331f0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
33200 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
33210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33220 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
33230 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
33240 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
33250 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
33260 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
33270 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
33280 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
33290 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
332a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
332b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
332c0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
332d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
332e0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
332f0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
33300 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
33310 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
33320 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
33330 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
33340 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
33350 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
33360 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
33370 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
33380 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
33390 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
333a0 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
333b0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
333c0 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
333d0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
333e0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
333f0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
33400 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
33410 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33420 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
33430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33440 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
33450 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
33460 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
33470 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
33480 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
33490 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
334a0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
334b0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
334c0 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
334d0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
334e0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
334f0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
33500 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33510 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
33520 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
33530 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
33540 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
33550 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
33560 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
33570 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
33580 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
33590 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
335a0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
335b0 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
335c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
335d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
335e0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
335f0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
33600 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
33610 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
33620 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
33630 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33640 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  or_toobig() inte
33650 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
33660 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
33670 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
33680 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
33690 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
336a0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
336b0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
336c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
336d0 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ror_nomem() inte
336e0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
336f0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
33700 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
33710 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
33720 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
33730 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
33740 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33750 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
33760 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
33770 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
33780 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33790 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
337a0 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
337b0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
337c0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
337d0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
337e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
337f0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
33800 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
33810 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
33820 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
33830 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33840 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
33850 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
33860 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
33870 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
33880 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
33890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
338a0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
338b0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
338c0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
338d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
338e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
338f0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
33900 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33910 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
33920 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33930 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
33940 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33950 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
33960 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
33970 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
33980 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
33990 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
339a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
339b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
339c0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
339d0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
339e0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
339f0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
33a00 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
33a10 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
33a20 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
33a30 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
33a40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
33a50 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
33a60 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
33a70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
33a80 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
33a90 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
33aa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33ab0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
33ac0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
33ad0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33ae0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33af0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
33b00 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
33b10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
33b20 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
33b30 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
33b40 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
33b50 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
33b60 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
33b70 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
33b80 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
33b90 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
33ba0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
33bb0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
33bc0 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
33bd0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
33be0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
33bf0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
33c00 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
33c10 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
33c20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33c30 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
33c40 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
33c50 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
33c60 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
33c70 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
33c80 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
33c90 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
33ca0 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
33cb0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
33cc0 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
33cd0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
33ce0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
33cf0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
33d00 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
33d10 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
33d20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
33d30 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
33d40 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
33d50 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
33d60 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
33d70 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
33d80 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
33d90 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
33da0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
33db0 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
33dc0 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
33dd0 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
33de0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
33df0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
33e00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
33e10 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33e20 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
33e30 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
33e40 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
33e50 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
33e60 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
33e70 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
33e80 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
33e90 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
33ea0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
33eb0 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
33ec0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
33ed0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
33ee0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
33ef0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
33f00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33f10 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
33f20 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
33f30 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
33f40 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
33f50 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
33f60 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
33f70 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
33f80 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
33f90 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
33fa0 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
33fb0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
33fc0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
33fd0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
33fe0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
33ff0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
34000 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
34010 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
34020 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
34030 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
34040 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
34050 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34060 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
34070 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
34080 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
34090 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
340a0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
340b0 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
340c0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
340d0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
340e0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
340f0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
34100 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
34110 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
34120 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34130 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
34140 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34150 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
34160 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
34170 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34180 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
34190 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
341a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
341b0 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
341c0 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
341d0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
341e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
341f0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
34200 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
34210 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
34220 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
34230 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
34240 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
34250 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
34260 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
34270 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
34280 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
34290 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
342a0 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
342b0 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
342c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
342d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
342e0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
342f0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
34300 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34310 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
34320 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
34330 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
34340 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34350 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
34360 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
34370 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
34380 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
34390 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
343a0 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
343b0 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
343c0 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
343d0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
343e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
343f0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
34400 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
34410 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
34420 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
34430 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
34440 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
34450 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
34460 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34470 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
34480 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
34490 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
344a0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
344b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
344c0 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
344d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
344e0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
344f0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
34500 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
34510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34520 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
34530 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
34540 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
34550 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34560 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
34570 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
34580 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34590 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
345a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
345b0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
345c0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
345d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
345e0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
345f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
34600 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34610 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
34620 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
34630 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
34640 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
34650 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
34660 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
34670 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
34680 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34690 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
346a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
346b0 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
346c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
346d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
346e0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
346f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34700 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
34710 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
34720 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34730 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
34740 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
34750 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
34760 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
34770 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34780 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
34790 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
347a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
347b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
347c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
347d0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
347e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
347f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
34800 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34810 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
34820 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
34830 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
34840 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
34850 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
34860 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
34870 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
34880 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
34890 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
348a0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
348b0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
348c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
348d0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
348e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
348f0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
34900 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
34910 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
34920 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
34930 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34940 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
34950 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34960 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
34970 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
34980 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34990 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
349a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
349b0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
349c0 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
349d0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
349e0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
349f0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
34a00 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
34a10 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
34a20 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
34a30 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
34a40 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
34a50 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
34a60 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
34a70 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
34a80 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
34a90 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
34aa0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
34ab0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
34ac0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
34ad0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
34ae0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
34af0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
34b00 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
34b10 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
34b20 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
34b30 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
34b40 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
34b50 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34b60 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
34b70 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
34b80 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
34b90 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
34ba0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
34bb0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
34bc0 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
34bd0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
34be0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
34bf0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
34c00 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
34c10 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
34c20 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
34c30 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
34c40 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
34c50 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
34c60 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
34c70 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
34c80 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
34c90 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
34ca0 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
34cb0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
34cc0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
34cd0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34ce0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
34cf0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
34d00 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
34d10 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
34d20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
34d30 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
34d40 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
34d50 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
34d60 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
34d70 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
34d80 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
34d90 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
34da0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
34db0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
34dc0 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
34dd0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
34de0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
34df0 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
34e00 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
34e10 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
34e20 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
34e30 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
34e40 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
34e50 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
34e60 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
34e70 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
34e80 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
34e90 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
34ea0 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
34eb0 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
34ec0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
34ed0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
34ee0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
34ef0 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
34f00 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
34f10 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
34f20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
34f30 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
34f40 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
34f50 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
34f60 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
34f70 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
34f80 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
34f90 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
34fa0 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
34fb0 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
34fc0 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
34fd0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
34fe0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
34ff0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
35000 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
35010 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
35020 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
35030 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
35040 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
35050 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
35060 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
35070 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
35080 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
35090 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
350a0 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
350b0 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
350c0 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
350d0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
350e0 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
350f0 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
35100 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
35110 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
35120 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
35130 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
35140 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
35150 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
35160 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
35170 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
35180 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
35190 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
351a0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
351b0 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
351c0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
351d0 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
351e0 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
351f0 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
35200 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
35210 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
35220 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
35230 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
35240 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35250 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
35260 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
35270 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
35280 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
35290 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
352a0 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
352b0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
352c0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
352d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
352e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
352f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
35300 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
35310 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35320 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
35330 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
35340 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
35350 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
35360 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
35370 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
35380 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
35390 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
353a0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
353b0 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
353c0 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
353d0 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
353e0 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
353f0 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
35400 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
35410 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
35420 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35430 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
35440 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
35450 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
35460 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
35470 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
35480 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
35490 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
354a0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
354b0 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
354c0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
354d0 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
354e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
354f0 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
35500 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
35510 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
35520 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
35530 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
35540 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
35550 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
35560 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
35570 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
35580 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
35590 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
355a0 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
355b0 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
355c0 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
355d0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
355e0 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
355f0 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
35600 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
35610 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
35620 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
35630 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
35640 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
35650 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
35660 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
35670 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
35680 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
35690 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
356a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
356b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
356c0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
356d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
356e0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
356f0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
35700 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
35710 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
35720 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
35730 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
35740 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
35750 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
35760 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
35770 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
35780 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
35790 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
357a0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
357b0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
357c0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
357d0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
357e0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
357f0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
35800 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35810 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
35820 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
35830 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
35840 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
35850 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
35860 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
35870 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
35880 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
35890 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
358a0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
358b0 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
358c0 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
358d0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
358e0 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
358f0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
35900 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
35910 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
35920 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
35930 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
35940 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
35950 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
35960 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
35970 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
35980 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
35990 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
359a0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
359b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
359c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
359d0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
359e0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
359f0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
35a00 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
35a10 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
35a20 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
35a30 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
35a40 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
35a50 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
35a60 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
35a70 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
35a80 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
35a90 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
35aa0 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
35ab0 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
35ac0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
35ad0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
35ae0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
35af0 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
35b00 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
35b10 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
35b20 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
35b30 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
35b40 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35b50 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
35b60 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
35b70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
35b80 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
35b90 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
35ba0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
35bb0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
35bc0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
35bd0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
35be0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
35bf0 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
35c00 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
35c10 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
35c20 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
35c30 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
35c40 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
35c50 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
35c60 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
35c70 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
35c80 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
35c90 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
35ca0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
35cb0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
35cc0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
35cd0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
35ce0 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
35cf0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
35d00 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
35d10 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
35d20 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
35d30 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
35d40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
35d50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
35d60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
35d70 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
35d80 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35d90 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
35da0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
35db0 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
35dc0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
35dd0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
35de0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
35df0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
35e00 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
35e10 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
35e20 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
35e30 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
35e40 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
35e50 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
35e60 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
35e70 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  .);..#ifdef SQLI
35e80 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a  TE_HAS_CODEC./*.
35e90 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
35ea0 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
35eb0 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
35ec0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
35ed0 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
35ee0 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
35ef0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
35f00 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
35f10 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
35f20 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
35f30 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
35f40 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
35f50 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
35f60 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
35f70 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
35f80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
35f90 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
35fa0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
35fb0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
35fc0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
35fd0 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  key */.);.int sq
35fe0 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20  lite3_key_v2(.  
35ff0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36010 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
36020 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
36030 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
36040 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  e,           /* 
36050 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  Name of the data
36060 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
36070 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
36080 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
36090 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
360a0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
360b0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
360c0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
360d0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
360e0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
360f0 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
36100 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
36110 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
36120 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
36130 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
36140 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
36150 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
36160 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
36170 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
36180 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
36190 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
361a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
361b0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
361c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
361d0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
361e0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
361f0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
36200 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
36210 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
36220 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73   key */.);.int s
36230 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28  qlite3_rekey_v2(
36240 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36260 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
36270 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
36280 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
36290 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20  Name,           
362a0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64  /* Name of the d
362b0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
362c0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
362d0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
362e0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
362f0 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
36300 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
36310 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74  ey for a SEE dat
36320 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
36330 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
36340 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f  ne of the SEE ro
36350 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
36360 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
36370 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a  3_activate_see(.
36380 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
36390 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
363a0 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
363b0 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
363c0 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  if..#ifdef SQLIT
363d0 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f  E_ENABLE_CEROD./
363e0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
363f0 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
36400 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61  for a CEROD data
36410 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
36420 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
36430 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72  e of the CEROD r
36440 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
36450 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
36460 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
36470 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
36480 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
36490 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
364a0 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
364b0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
364c0 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
364d0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
364e0 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
364f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
36500 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
36510 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
36520 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
36530 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
36540 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
36550 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
36560 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
36570 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
36580 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
36590 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
365a0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
365b0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
365c0 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
365d0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
365e0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
365f0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
36600 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
36610 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
36620 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
36630 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
36640 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
36650 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
36660 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
36670 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
36680 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
36690 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
366a0 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
366b0 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
366c0 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
366d0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
366e0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
366f0 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20  If the xSleep() 
36700 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
36710 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
36720 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
36730 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f  correctly, or no
36740 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74  t implemented at
36750 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68  .** all, then th
36760 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
36770 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61  lite3_sleep() ma
36780 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74  y deviate from t
36790 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a  he description.*
367a0 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  * in the previou
367b0 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f  s paragraphs..*/
367c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
367d0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
367e0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
367f0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
36800 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
36810 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
36820 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
36830 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
36840 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
36850 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
36860 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
36870 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
36880 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
36890 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
368a0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
368b0 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
368c0 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
368d0 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
368e0 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
368f0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
36900 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
36910 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
36920 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
36930 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
36940 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
36950 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
36960 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
36970 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
36980 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
36990 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
369a0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
369b0 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
369c0 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
369d0 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
369e0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
369f0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
36a00 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
36a10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36a20 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
36a30 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
36a40 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
36a50 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
36a60 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
36a70 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
36a80 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
36a90 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
36aa0 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
36ab0 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
36ac0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
36ad0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
36ae0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
36af0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
36b00 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
36b10 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
36b20 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
36b30 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
36b40 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
36b50 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
36b60 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
36b70 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
36b80 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
36b90 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
36ba0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
36bb0 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
36bc0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
36bd0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
36be0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
36bf0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
36c00 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
36c10 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
36c20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
36c30 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
36c40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
36c50 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
36c60 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
36c70 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
36c80 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
36c90 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
36ca0 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
36cb0 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
36cc0 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
36cd0 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
36ce0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
36cf0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
36d00 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
36d10 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
36d20 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
36d30 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
36d40 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
36d50 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
36d60 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
36d70 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
36d80 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
36d90 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
36da0 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
36db0 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
36dc0 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
36dd0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
36de0 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69  3_open] or [sqli
36df0 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f  te3_open_v2].  O
36e00 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
36e10 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
36e20 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
36e30 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
36e40 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20  files may fail. 
36e50 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65   Here is an.** e
36e60 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f  xample of how to
36e70 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43   do this using C
36e80 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69 6e 64  ++ with the Wind
36e90 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a  ows Runtime:.**.
36ea0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
36eb0 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20  pre>.** LPCWSTR 
36ec0 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a  zPath = Windows:
36ed0 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63  :Storage::Applic
36ee0 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65  ationData::Curre
36ef0 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  nt->.** &nbsp;  
36f00 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64     TemporaryFold
36f10 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29  er->Path->Data()
36f20 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42  ;.** char zPathB
36f30 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20  uf&#91;MAX_PATH 
36f40 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d  + 1&#93;;.** mem
36f50 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c  set(zPathBuf, 0,
36f60 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66   sizeof(zPathBuf
36f70 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54  ));.** WideCharT
36f80 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54  oMultiByte(CP_UT
36f90 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31  F8, 0, zPath, -1
36fa0 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65  , zPathBuf, size
36fb0 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a  of(zPathBuf),.**
36fc0 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c   &nbsp;     NULL
36fd0 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69  , NULL);.** sqli
36fe0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
36ff0 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  ry = sqlite3_mpr
37000 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68  intf("%s", zPath
37010 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  Buf);.** </pre><
37020 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a  /blockquote>.*/.
37030 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68  SQLITE_EXTERN ch
37040 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70  ar *sqlite3_temp
37050 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
37060 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
37070 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
37080 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61 73 65  Holding Database
37090 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
370a0 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
370b0 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
370c0 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
370d0 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
370e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
370f0 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
37100 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
37110 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  l database files
37120 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 77 69  .** specified wi
37130 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  th a relative pa
37140 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65 61 74  thname and creat
37150 65 64 20 6f 72 20 61 63 63 65 73 73 65 64 20 62  ed or accessed b
37160 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68 65 6e  y.** SQLite when
37170 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
37180 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74  n windows [sqlit
37190 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20 77 69  e3_vfs | VFS] wi
371a0 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a  ll be assumed.**
371b0 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76 65 20   to be relative 
371c0 74 6f 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  to that director
371d0 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20 76 61  y.)^ ^If this va
371e0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
371f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  .** pointer, the
37200 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
37210 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61 62 61   that all databa
37220 73 65 20 66 69 6c 65 73 20 73 70 65 63 69 66 69  se files specifi
37230 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72 65 6c  ed.** with a rel
37240 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61  ative pathname a
37250 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74  re relative to t
37260 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
37270 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tory.** for the 
37280 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74  process.  Only t
37290 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 6d  he windows VFS m
372a0 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68 69 73  akes use of this
372b0 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61   global.** varia
372c0 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e 6f 72  ble; it is ignor
372d0 65 64 20 62 79 20 74 68 65 20 75 6e 69 78 20 56  ed by the unix V
372e0 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69  FS..**.** Changi
372f0 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ng the value of 
37300 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 77 68  this variable wh
37310 69 6c 65 20 61 20 64 61 74 61 62 61 73 65 20 63  ile a database c
37320 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  onnection is.** 
37330 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c 74 20  open can result 
37340 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64 61 74  in a corrupt dat
37350 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  abase..**.** It 
37360 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
37370 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
37380 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
37390 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
373a0 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
373b0 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
373c0 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
373d0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
373e0 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
373f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37400 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
37410 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
37420 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
37430 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
37440 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
37450 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
37460 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
37470 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
37480 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
37490 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
374a0 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
374b0 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
374c0 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
374d0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
374e0 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
374f0 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
37500 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61  ..**.** ^The [da
37510 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  ta_store_directo
37520 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
37530 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
37540 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
37550 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
37560 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
37570 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
37580 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
37590 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61  more,.** the [da
375a0 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  ta_store_directo
375b0 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
375c0 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
375d0 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
375e0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
375f0 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
37600 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
37610 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
37620 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
37630 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
37640 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
37650 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
37660 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
37670 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
37680 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
37690 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
376a0 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
376b0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
376c0 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
376d0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
376e0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
376f0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
37700 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
37710 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
37720 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  ta_store_directo
37730 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
37740 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
37750 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
37760 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 61 74  har *sqlite3_dat
37770 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  a_directory;../*
37780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
37790 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
377a0 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f  it Mode.** KEYWO
377b0 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
377c0 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68   mode}.**.** ^Th
377d0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
377e0 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
377f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
37800 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
37810 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
37820 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37830 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
37840 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
37850 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
37860 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ly.  ^Autocommit
37870 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
37880 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f  efault..** ^Auto
37890 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
378a0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
378b0 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
378c0 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
378d0 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
378e0 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
378f0 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
37900 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
37910 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
37920 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
37930 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
37940 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
37950 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
37960 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
37970 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
37980 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
37990 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
379a0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
379b0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
379c0 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
379d0 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
379e0 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
379f0 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
37a00 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
37a10 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
37a20 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
37a30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
37a40 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
37a50 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
37a60 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
37a70 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
37a80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
37a90 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
37aa0 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
37ab0 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
37ac0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
37ad0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
37ae0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
37af0 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
37b00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
37b10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
37b20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
37b30 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
37b40 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
37b50 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
37b60 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
37b70 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
37b80 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
37b90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
37ba0 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
37bb0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
37bc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37bd0 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
37be0 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
37bf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
37c00 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74  ongs.  ^The [dat
37c10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37c20 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
37c30 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
37c40 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
37c50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37c60 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  ion].** that was
37c70 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
37c80 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
37c90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
37ca0 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
37cb0 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
37cc0 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
37cd0 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
37ce0 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
37cf0 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
37d00 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
37d10 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
37d20 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
37d30 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
37d40 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20  he Filename For 
37d50 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
37d60 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
37d70 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65   sqlite3_db_file
37d80 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66  name(D,N) interf
37d90 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
37da0 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e  inter to a filen
37db0 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ame.** associate
37dc0 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20  d with database 
37dd0 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  N of connection 
37de0 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61  D.  ^The main da
37df0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68  tabase file.** h
37e00 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69  as the name "mai
37e10 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  n".  If there is
37e20 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61 74   no attached dat
37e30 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64  abase N on the d
37e40 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
37e50 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64  ction D, or if d
37e60 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20 74  atabase N is a t
37e70 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d  emporary or in-m
37e80 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20  emory database, 
37e90 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  then.** a NULL p
37ea0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
37eb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
37ec0 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64  ilename returned
37ed0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
37ee0 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74 20  n is the output 
37ef0 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50  of the.** xFullP
37f00 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f  athname method o
37f10 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49  f the [VFS].  ^I
37f20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
37f30 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
37f40 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75  ill be an absolu
37f50 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65  te pathname, eve
37f60 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  n if the filenam
37f70 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65  e used.** to ope
37f80 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  n the database o
37f90 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20  riginally was a 
37fa0 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20  URI or relative 
37fb0 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e  pathname..*/.con
37fc0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
37fd0 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c  _db_filename(sql
37fe0 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20  ite3 *db, const 
37ff0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a  char *zDbName);.
38000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38010 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20   Determine if a 
38020 64 61 74 61 62 61 73 65 20 69 73 20 72 65 61 64  database is read
38030 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  -only.**.** ^The
38040 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64   sqlite3_db_read
38050 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66  only(D,N) interf
38060 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69 66  ace returns 1 if
38070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a   the database N.
38080 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e  ** of connection
38090 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c   D is read-only,
380a0 20 30 20 69 66 20 69 74 20 69 73 20 72 65 61 64   0 if it is read
380b0 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66  /write, or -1 if
380c0 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65   N is not.** the
380d0 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62   name of a datab
380e0 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f  ase on connectio
380f0 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  n D..*/.int sqli
38100 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28  te3_db_readonly(
38110 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e  sqlite3 *db, con
38120 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
38130 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38140 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
38150 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
38160 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
38170 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38180 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
38190 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
381a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
381b0 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
381c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
381d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
381e0 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
381f0 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
38200 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
38210 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
38220 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
38230 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
38240 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
38250 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
38260 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38270 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
38280 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
38290 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
382a0 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
382b0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
382c0 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
382d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
382e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
382f0 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
38300 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
38310 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
38320 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
38330 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
38340 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
38350 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
38360 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
38370 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
38380 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
38390 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
383a0 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
383b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
383c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
383d0 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
383e0 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
383f0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
38400 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
38410 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
38420 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
38430 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
38440 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
38450 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
38460 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
38470 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
38480 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
38490 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
384a0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
384b0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
384c0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
384d0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
384e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
384f0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
38500 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38510 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
38520 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
38530 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
38540 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
38550 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
38560 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
38570 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
38580 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
38590 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
385a0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
385b0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
385c0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a  rollback_hook().
385d0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
385e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
385f0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
38600 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20  n..** ^The pArg 
38610 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
38620 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
38630 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  e callback..** ^
38640 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
38650 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
38660 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
38670 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
38680 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
38690 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
386a0 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
386b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
386c0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c  commit_hook(D,C,
386d0 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  P) and sqlite3_r
386e0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43  ollback_hook(D,C
386f0 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ,P) functions.**
38700 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72   return the P ar
38710 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
38720 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66  previous call of
38730 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
38740 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  on.** on the sam
38750 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38760 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
38770 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
38780 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63  rst call for eac
38790 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e  h function on D.
387a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69  .**.** The commi
387b0 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68  t and rollback h
387c0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61 72  ook callbacks ar
387d0 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  e not reentrant.
387e0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
387f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
38800 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
38810 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
38820 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
38830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38840 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
38850 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
38860 20 61 63 74 69 6f 6e 73 0a 2a 2a