System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 22d40cfeb0b815b0fd5112f2a65117d891d367ee:


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 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 37 2e 31 34 22 0a 23 64 65 66 69 6e 65 20 53  .7.14".#define S
1030: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1040: 4d 42 45 52 20 33 30 30 37 30 31 34 0a 23 64 65  MBER 3007014.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 32  CE_ID      "2012
1070: 2d 30 38 2d 32 34 20 30 31 3a 30 37 3a 35 32 20  -08-24 01:07:52 
1080: 64 34 63 64 36 30 31 37 63 39 38 37 35 39 34 37  d4cd6017c9875947
1090: 61 30 35 62 31 64 63 33 36 35 33 38 64 34 32 37  a05b1dc36538d427
10a0: 32 66 62 31 38 37 33 39 22 0a 0a 2f 2a 0a 2a 2a  2fb18739"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
24a0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
24b0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
24c0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
24d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
24e0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
24f0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2500: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2510: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2530: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2540: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
2550: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
2560: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
2570: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
2580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2590: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
25a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25b0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
25c0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
25d0: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
25e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
25f0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2600: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2610: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2620: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2630: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2640: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
2650: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
2660: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
2670: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
2680: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2690: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26a0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
26b0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
26c0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
26d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
26e0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
26f0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2700: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2710: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2720: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2730: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2740: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
2750: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
2760: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2770: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
2780: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
2790: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
27b0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
27c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
27d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
27e0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
27f0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2800: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2810: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2820: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2830: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2850: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
2870: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2880: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2890: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
28a0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
28b0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
28c0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
28d0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
28e0: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
28f0: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2900: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2910: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2930: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2940: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2950: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2960: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
2970: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2980: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
29a0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
29b0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
29c0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
29d0: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
29e0: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
29f0: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2a00: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2a10: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2a20: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2a30: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2a40: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2a50: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2a60: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
2a70: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
2a80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2aa0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2ab0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2ac0: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
2ad0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2ae0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2af0: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2b00: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2b10: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2b20: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2b30: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b40: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2b60: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
2b70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
2b80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
2b90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
2ba0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
2bb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
2bc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2bd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
2c00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
2c10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
2c20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
2c30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2c40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
2c50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
2c60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
2c70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
2c80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
2c90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
2ca0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
2cb0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2cd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2ce0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
2cf0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66  ments.** and unf
2d00: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2d10: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68  backups, then th
2d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d30: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a  ction becomes.**
2d40: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f   an unusable "zo
2d50: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c  mbie" which will
2d60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
2d70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68  e deallocated wh
2d80: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70  en the.** last p
2d90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f  t is finalized o
2db0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  r the last sqlit
2dc0: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20  e3_backup is.** 
2dd0: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73  finished.  The s
2de0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2df0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
2e00: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2e10: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e  with.** host lan
2e20: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20  guages that are 
2e30: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65  garbage collecte
2e40: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65  d, and where the
2e50: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a   order in which.
2e60: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61  ** destructors a
2e70: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62  re called is arb
2e80: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70  itrary..**.** Ap
2e90: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2eb0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
2ec0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
2ed0: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73  atements],.** [s
2ee0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2ef0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2f00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
2f10: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f20: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20  backup_finish | 
2f30: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c  finish] all [sql
2f40: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
2f50: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a  ects associated.
2f60: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
2f70: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2f80: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2f90: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2fa0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71  ject.  ^If.** sq
2fb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 73  lite3_close() is
2fc0: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2fd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fe0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2ff0: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3030: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
3050: 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  it returns SQLIT
3060: 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61  E_OK but the dea
3070: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
3080: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
3090: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
30a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30b0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
30c0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
30d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
30e0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
30f0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
3100: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
3110: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
3120: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
3130: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
3140: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
3150: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
3160: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
3170: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
3180: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3190: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
31a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
31b0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
31c0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
31d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
31e0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
31f0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
3200: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3210: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
3220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
3230: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
3240: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
3250: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
3260: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
3270: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
3280: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
3290: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
32a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
32b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
32c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
32d0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
32e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
32f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
3300: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3310: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3320: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3330: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3340: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3350: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3360: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3370: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3380: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
3390: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
33a0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
33b0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
33c0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
33d0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
33e0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
33f0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
3400: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3410: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3420: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
3430: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3440: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3450: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3460: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3470: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3480: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3490: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
34a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
34c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
34d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
34e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
34f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3500: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3510: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3520: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3530: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3540: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3550: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3560: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3570: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3580: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3590: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
35a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
35b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
35c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
35e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
35f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3600: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3610: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3620: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3630: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3640: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3650: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3660: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3670: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3680: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3690: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
36a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
36b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
36c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
36d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
36e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
36f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3700: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3710: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3720: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3730: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3740: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3750: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3760: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3770: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3780: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3790: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
37a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
37b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
37c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
37d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
37e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
37f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3800: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3810: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3820: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3830: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3840: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3850: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3860: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3870: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3880: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3890: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
38a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
38b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
38d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
38e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3900: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3910: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3920: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3930: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3940: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3950: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3960: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3970: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3980: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3990: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
39a0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
39b0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
39c0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
39d0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39e0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39f0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3a00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3a10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3a20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3a30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3a40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3a50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3a60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3a70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3a80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3a90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3aa0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3ab0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3ac0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3ad0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3ae0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3af0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3b00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3b10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3b20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3b30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3b40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3b60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3b70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3b80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3b90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3ba0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3bb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3bc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3bd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3be0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3bf0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3c00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3c10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3c20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3c30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3c40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3c50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3c60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3c70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3c80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3ca0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3cb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3cc0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3cd0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3ce0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3cf0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3d00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3d10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3d20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3d30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3d40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3d50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3d60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3d70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3d80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3d90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3da0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3db0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3dc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3dd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3de0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3df0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3e00: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3e10: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3e20: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3e30: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
3e40: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
3e50: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3e60: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3e70: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3e80: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3e90: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3ea0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3eb0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3ec0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3ed0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ee0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3ef0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3f00: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3f10: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3f20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f30: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3f40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3f50: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3f60: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3f70: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3f80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3f90: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3fa0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3fb0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3fc0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3fd0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3fe0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3ff0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4000: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4010: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4020: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4030: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
4040: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
4050: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
4060: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
4070: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40a0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
40b0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
40c0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
40f0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4100: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4110: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4120: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4130: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4140: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4170: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
4180: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
4190: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
41c0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
41d0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
41e0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
41f0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4200: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4220: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4230: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4240: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4250: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
4260: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4270: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4280: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4290: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
42a0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
42b0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
42c0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
42d0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
42e0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
42f0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4300: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4310: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4320: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4330: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4340: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4350: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
4360: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
4370: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
4380: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
43a0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
43b0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
43c0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
43d0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
43e0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43f0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4400: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4410: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4420: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4440: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4450: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4460: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4490: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
44a0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
44b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44c0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
44d0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
44e0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44f0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4510: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4520: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4530: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4550: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4560: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4570: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4580: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4590: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
45a0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
45b0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
45c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
45d0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
45e0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45f0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4600: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4620: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4630: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4640: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4650: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4670: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4680: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4690: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
46a0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
46b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
46c0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
46d0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
46e0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4700: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4710: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4720: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4730: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4760: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4770: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4780: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47a0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47b0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
47c0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
47d0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
47e0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47f0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4800: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4810: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4830: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4840: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4860: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4870: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4880: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4890: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
48a0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
48b0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
48c0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
48d0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48f0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4900: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4910: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4920: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4930: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4940: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4950: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4970: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4980: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4990: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
49b0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
49c0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
49d0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
49e0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4a00: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4a10: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4a20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4a30: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4a40: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a50: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a60: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a70: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a80: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a90: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4aa0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4ab0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ad0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4ae0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4af0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4b00: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4b10: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4b20: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b30: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b40: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b50: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b60: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b70: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b80: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b90: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ba0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4bb0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4bc0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4bd0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4be0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bf0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4c00: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4c10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4c20: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c50: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c60: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c70: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c80: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c90: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4ca0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4cb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4cc0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4cd0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4ce0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cf0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4d00: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4d10: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4d20: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d30: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d50: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d60: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d70: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d80: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d90: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4da0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4db0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4dc0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4dd0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4de0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4df0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4e00: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4e10: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4e20: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e30: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e50: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e60: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e80: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e90: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4ea0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4eb0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4ec0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ed0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4ee0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ef0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4f00: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4f10: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4f20: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f30: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4f40: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4f50: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4f60: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4f70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4f80: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4f90: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4fa0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4fb0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4fc0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4fd0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4fe0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4ff0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
5000: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
5010: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
5020: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5080: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
51e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51f0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5200: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5210: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5230: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5240: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5250: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52d0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5380: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5390: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5540: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5550: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
55b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
55d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
55e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
55f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5600: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5610: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5630: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5650: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5670: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5680: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5690: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
56a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56b0: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
56c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
56d0: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
56e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
56f0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5700: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
5710: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
5720: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5730: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
5740: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
5750: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5760: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5770: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5780: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5790: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
57a0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
57b0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
57c0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
57d0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
57e0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
57f0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5800: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5810: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5820: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5830: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5840: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5850: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5860: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5870: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
5880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5890: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
58a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
58b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
58c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
58d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58e0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
58f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5900: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5910: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5930: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5940: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5950: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5960: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5980: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5990: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
59a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
59b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59c0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
59d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
59e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a00: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5a10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5a20: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5a50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5a60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5a70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5a80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a90: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
5aa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5ab0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5ac0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ae0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5af0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5b00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5b30: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5b40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b60: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5b70: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5b80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5bb0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5bc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5be0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5bf0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5c00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c20: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5c30: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5c40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c60: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5c70: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5c80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ca0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5cb0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5cc0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cd0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cf0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5d00: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5d10: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d20: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d40: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5d50: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5d60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d90: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5da0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5db0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5dc0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5de0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5df0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
5e00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5e10: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5e30: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5e40: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5e50: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5e60: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5e70: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5e80: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5e90: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5ea0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5eb0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
5ec0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
5ed0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
5ee0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
5ef0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5f00: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5f10: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5f20: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5f30: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5f40: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5f50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5f60: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5f70: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5f80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5f90: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
5fa0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
5fb0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
5fc0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
5fd0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5fe0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5ff0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6000: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6010: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
6020: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6030: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6040: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6050: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6060: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6070: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6080: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6090: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
60a0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
60b0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
60c0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
60d0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
60e0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
60f0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6100: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6110: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
6120: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
6130: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
6140: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6150: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6160: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6170: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6180: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6190: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
61a0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
61b0: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
61c0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
61d0: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
61e0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
61f0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
6200: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
6210: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
6220: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
6230: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
6240: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6260: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
6270: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6280: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6290: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
62a0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
62b0: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
62c0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
62d0: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64  unchanged..*/.#d
62e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
62f0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
6300: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6310: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
6320: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6330: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
6340: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6360: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6370: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6380: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6390: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
63b0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
63c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
63d0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
63e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
63f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6400: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
6410: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6420: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
6430: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6440: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6450: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
6460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6470: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6480: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6490: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
64a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
64b0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
64c0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
64d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
64e0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
64f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6500: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
6510: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6520: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
6530: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
6540: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6550: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6560: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
6570: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6580: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6590: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
65a0: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
65b0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
65c0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
65d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
65e0: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
65f0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6600: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6610: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
6620: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
6630: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6640: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6650: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6660: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6670: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6680: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6690: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
66a0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
66b0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
66c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
66d0: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
66e0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
66f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6700: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6710: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6720: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6730: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6740: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6750: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6760: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6770: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6780: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6790: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
67a0: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
67b0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
67c0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
67d0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
67e0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
67f0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6800: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6810: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6820: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6830: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6840: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6850: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6860: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6870: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6880: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6890: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
68a0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
68b0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
68c0: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
68d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
68e0: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
68f0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6900: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6910: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6920: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6930: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6940: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6950: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6960: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6970: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
6980: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
6990: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
69a0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
69b0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
69c0: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
69d0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
69e0: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
69f0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6a00: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
6a10: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
6a20: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
6a30: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
6a40: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
6a50: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
6a60: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
6a70: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
6a80: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
6a90: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
6aa0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6ab0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6ac0: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
6ad0: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
6ae0: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
6af0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
6b00: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
6b10: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
6b20: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
6b30: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
6b40: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
6b50: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
6b60: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
6b70: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
6b80: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
6b90: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
6ba0: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
6bb0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6bc0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6bd0: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
6be0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
6bf0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
6c00: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
6c10: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
6c20: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
6c30: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
6c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
6c60: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
6c80: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
6c90: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
6ca0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6cb0: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
6cc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6cd0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
6ce0: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
6cf0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
6d00: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
6d10: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
6d20: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
6d30: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
6d40: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
6d50: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
6d60: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
6d70: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6d80: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
6d90: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
6da0: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
6db0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
6dc0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
6dd0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
6de0: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
6df0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
6e00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6e10: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6e20: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
6e30: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
6e40: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
6e50: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
6e60: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
6e70: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
6e80: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
6e90: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
6ea0: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
6eb0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
6ec0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
6ed0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
6ee0: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
6ef0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
6f00: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6f10: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
6f20: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
6f30: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
6f40: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
6f50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6f60: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
6f70: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
6f80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6f90: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
6fa0: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
6fb0: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
6fc0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6fd0: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
6fe0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
6ff0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7000: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7010: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7020: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7030: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7040: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7050: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7060: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7070: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7080: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7090: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
70a0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
70b0: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
70c0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
70d0: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
70e0: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
70f0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7120: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7130: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7140: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7150: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7160: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7170: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7180: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7190: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
71a0: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
71b0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
71c0: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
71d0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
71e0: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
71f0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7200: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7210: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7220: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7230: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7240: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7250: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7260: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7270: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7280: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7290: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
72a0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
72b0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
72c0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
72d0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
72e0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
72f0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
7300: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
7310: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
7320: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
7330: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
7340: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7350: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7360: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7370: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7380: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7390: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
73a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
73b0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
73c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
73d0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
73e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
73f0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
7400: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7410: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
7420: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7430: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
7440: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
7450: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7460: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
7470: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
7480: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7490: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
74a0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
74b0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
74c0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
74d0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
74e0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
74f0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
7500: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
7510: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
7520: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
7530: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
7540: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
7550: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
7560: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
7570: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
7580: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7590: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
75a0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
75b0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
75c0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
75d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
75e0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
75f0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7600: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7610: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7620: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
7630: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
7640: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7650: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7660: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7670: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7680: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7690: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
76a0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
76b0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
76c0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
76d0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
76e0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
76f0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7700: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7710: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7720: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7730: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7740: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7750: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7760: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7770: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7780: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7790: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
77a0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
77b0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
77c0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
77d0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
77e0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
77f0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7800: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7810: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7820: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7830: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7840: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7850: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7860: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7870: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7880: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7890: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
78a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
78b0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
78c0: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
78d0: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
78e0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
78f0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7900: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7910: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7920: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7930: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7940: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7950: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7960: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7970: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7980: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7990: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
79a0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
79b0: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
79c0: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
79d0: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
79e0: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
79f0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7a00: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7a10: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7a20: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7a30: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7a40: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7a50: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7a60: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7a70: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7a80: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7a90: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7aa0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7ac0: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7ad0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7ae0: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7af0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b00: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7b10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b20: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7b30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b40: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b60: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7b70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b80: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7ba0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7bb0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7bc0: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7bd0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7be0: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7bf0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7c00: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7c10: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7c20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7c30: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7c40: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7c50: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
7c60: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7c70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7c80: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
7c90: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
7ca0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
7cb0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7cc0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7cd0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
7ce0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
7cf0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
7d00: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
7d10: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
7d20: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7d30: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7d40: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7d50: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
7d60: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7d70: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
7d80: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
7d90: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
7da0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7db0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7dc0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7dd0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7de0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7df0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7e00: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
7e10: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
7e20: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
7e30: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7e40: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7e50: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
7e60: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
7e70: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
7e80: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
7e90: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
7ea0: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
7eb0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
7ec0: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
7ed0: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
7ee0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7ef0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
7f00: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
7f10: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
7f20: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
7f30: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7f40: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7f50: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
7f60: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
7f70: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7f80: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7f90: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7fa0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
7fb0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
7fc0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
7fd0: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
7fe0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7ff0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
8000: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
8010: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8020: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8030: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
8040: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
8050: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8060: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8070: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8080: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8090: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
80a0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
80b0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
80c0: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
80d0: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
80e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
80f0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8100: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8110: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
8120: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
8130: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8140: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
8150: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8160: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8170: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8180: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8190: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
81a0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
81b0: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
81c0: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
81d0: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
81e0: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
81f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8200: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
8210: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
8220: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8230: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8240: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8250: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8260: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8270: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8280: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8290: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
82a0: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
82b0: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
82c0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
82d0: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
82e0: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
82f0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
8300: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8310: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
8320: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8330: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
8340: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8350: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8360: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
8370: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8380: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8390: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
83a0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
83b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
83c0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
83d0: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
83e0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
83f0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
8400: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
8410: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
8420: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
8430: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
8440: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
8450: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
8460: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
8470: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
8480: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8490: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
84a0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
84b0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
84c0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
84d0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
84e0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
84f0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8500: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8510: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8520: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8530: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8540: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8550: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
8560: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8570: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8580: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8590: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
85a0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
85b0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
85c0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
85d0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
85e0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
85f0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
8600: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
8610: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
8620: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
8630: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8640: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
8650: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
8660: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8670: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
8680: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
8690: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
86a0: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
86b0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
86c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
86d0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
86e0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
86f0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
8700: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
8710: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
8720: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
8730: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
8740: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
8750: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
8760: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
8770: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
8780: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
8790: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
87a0: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
87b0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
87c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
87d0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
87e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
87f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8800: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
8810: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8820: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
8830: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
8840: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
8850: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
8860: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
8870: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
8880: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
8890: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
88a0: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
88b0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
88c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
88d0: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
88e0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
88f0: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
8900: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
8910: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
8920: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
8930: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
8940: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
8950: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
8960: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
8970: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
8980: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
8990: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
89a0: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
89b0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
89c0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
89d0: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
89e0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
89f0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8a00: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
8a10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8a20: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8a30: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8a40: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
8a50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
8a60: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
8a70: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
8a80: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
8a90: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
8aa0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
8ab0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8ac0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8ad0: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8ae0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8af0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8b00: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
8b10: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68  MITTED]].** ^(Th
8b20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8b30: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70  SYNC_OMITTED] op
8b40: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
8b50: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a  d internally by.
8b60: 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65  ** SQLite and se
8b70: 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20  nt to all VFSes 
8b80: 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61  in place of a ca
8b90: 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20  ll to the xSync 
8ba0: 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74  method.** when t
8bb0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
8bc0: 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47  ection has [PRAG
8bd0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20  MA synchronous] 
8be0: 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a  set to OFF.)^.**
8bf0: 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65   Some specialize
8c00: 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69  d VFSes need thi
8c10: 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65  s signal in orde
8c20: 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72  r to operate cor
8c30: 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b  rectly.** when [
8c40: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8c50: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
8c60: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20  hronous=OFF] is 
8c70: 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a  set, but most .*
8c80: 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e  * VFSes do not n
8c90: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
8ca0: 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  and should silen
8cb0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
8cc0: 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69  opcode..** Appli
8cd0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
8ce0: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
8cf0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8d00: 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70   with this.** op
8d10: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
8d20: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
8d30: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
8d40: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8d50: 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72  Ses.** that do r
8d60: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
8d70: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8d80: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
8d90: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
8da0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
8db0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
8dc0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
8dd0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
8de0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
8df0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
8e00: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
8e10: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
8e20: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
8e30: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
8e40: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
8e50: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
8e60: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
8e70: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
8e80: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
8e90: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
8ea0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
8eb0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
8ec0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
8ed0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
8ee0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
8ef0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
8f00: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
8f10: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
8f20: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
8f30: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
8f40: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
8f50: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
8f60: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
8f70: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
8f80: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
8f90: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
8fa0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
8fb0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
8fc0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
8fd0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
8fe0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
8ff0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9000: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9010: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9020: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9030: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9040: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9050: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9060: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9070: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9080: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9090: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
90a0: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
90b0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
90c0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
90d0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
90e0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
90f0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9100: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9110: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9120: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9130: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9140: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9150: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9160: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9170: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9180: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9190: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
91a0: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
91b0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
91c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
91d0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
91e0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
91f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9200: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9210: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9220: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9230: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9240: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9250: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9260: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9270: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9280: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9290: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
92a0: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
92b0: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
92c0: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
92d0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
92e0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
92f0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9300: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9310: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9320: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9330: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9340: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9350: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9360: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9370: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9380: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9390: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
93a0: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
93b0: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
93c0: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
93d0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
93e0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
93f0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9400: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9410: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9420: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9430: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9440: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9450: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9460: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9470: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9480: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9490: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
94a0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
94b0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
94c0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
94d0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
94e0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
94f0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9500: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9510: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9520: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9530: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9540: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9550: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9560: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9570: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9580: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9590: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
95a0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
95b0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
95c0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
95d0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
95e0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
95f0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9600: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9610: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9620: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
9630: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
9640: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
9650: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
9660: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
9670: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
9680: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
9690: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
96a0: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
96b0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
96c0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
96d0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
96e0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
96f0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
9700: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
9710: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
9720: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
9730: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
9740: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
9750: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
9760: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9770: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9780: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9790: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
97a0: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
97b0: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
97c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
97d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
97e0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
97f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
9800: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
9810: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
9820: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
9830: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
9840: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
9850: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
9860: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
9870: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
9880: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
9890: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
98a0: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
98b0: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
98c0: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
98d0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
98e0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
98f0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
9900: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9910: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
9920: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9930: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
9940: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
9950: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
9960: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
9970: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
9980: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
9990: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
99a0: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
99b0: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
99c0: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
99d0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
99e0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
99f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
9a00: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
9a10: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
9a20: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
9a30: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
9a40: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9a50: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
9a60: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
9a70: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
9a80: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
9a90: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
9aa0: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
9ab0: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
9ac0: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
9ad0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
9ae0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
9af0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
9b00: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
9b10: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
9b20: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
9b30: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
9b40: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
9b50: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
9b60: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
9b70: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
9b80: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
9b90: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
9ba0: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
9bb0: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
9bc0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
9bd0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
9be0: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
9bf0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
9c00: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
9c10: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
9c20: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
9c30: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
9c40: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
9c50: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
9c60: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
9c70: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
9c80: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
9c90: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
9ca0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
9cb0: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
9cc0: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
9cd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9ce0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
9cf0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
9d00: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
9d10: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
9d20: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
9d30: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
9d40: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
9d50: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
9d60: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
9d70: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
9d80: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
9d90: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
9da0: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
9db0: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
9dc0: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
9dd0: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
9de0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9df0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
9e00: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
9e10: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
9e20: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
9e30: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
9e40: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
9e50: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
9e60: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
9e70: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
9e80: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
9e90: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
9ea0: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
9eb0: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
9ec0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
9ed0: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
9ee0: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
9ef0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
9f00: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
9f10: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
9f20: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
9f30: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
9f40: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
9f50: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
9f60: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
9f70: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
9f80: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
9f90: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
9fa0: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
9fb0: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
9fc0: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
9fd0: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
9fe0: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
9ff0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a000: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a010: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a020: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  t.  ^If the [SQL
a030: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a040: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a050: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
a060: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
a070: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
a080: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
a090: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
a0a0: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
a0b0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
a0c0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
a0d0: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
a0e0: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
a0f0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
a100: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
a110: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
a120: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a130: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
a140: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
a150: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
a160: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
a170: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
a180: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
a190: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
a1a0: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
a1b0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
a1c0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
a1d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
a1e0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
a1f0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
a200: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
a210: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
a220: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
a230: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
a240: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
a250: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
a260: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
a270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a280: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
a290: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
a2a0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
a2b0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
a2c0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
a2d0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
a2e0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
a2f0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
a300: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
a310: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
a320: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
a330: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
a340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a350: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
a360: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
a370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a380: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a390: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
a3a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a3b0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
a3c0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
a3d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a3e0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
a3f0: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
a400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a410: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a420: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
a430: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a440: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
a450: 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a          14../*.*
a460: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
a470: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
a480: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
a490: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
a4a0: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
a4b0: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
a4c0: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
a4d0: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
a4e0: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
a4f0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
a500: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
a510: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
a520: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
a530: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
a540: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
a550: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
a560: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
a570: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
a580: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
a590: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
a5a0: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
a5b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
a5c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
a5d0: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
a5e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a5f0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
a600: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
a610: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
a620: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
a630: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
a640: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
a650: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
a660: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
a670: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
a680: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
a690: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
a6a0: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
a6b0: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
a6c0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
a6d0: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
a6e0: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
a6f0: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
a700: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
a710: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
a720: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
a730: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
a740: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
a750: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
a760: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
a770: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
a780: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
a790: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
a7a0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
a7b0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
a7c0: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
a7d0: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
a7e0: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
a7f0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
a800: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
a810: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
a820: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
a830: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
a840: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
a850: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
a860: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
a870: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
a880: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
a890: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
a8a0: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
a8b0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
a8c0: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
a8d0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
a8e0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
a8f0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
a900: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
a910: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
a920: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
a930: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
a940: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
a950: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
a960: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
a970: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
a980: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
a990: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
a9a0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
a9b0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
a9c0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
a9d0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
a9e0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
a9f0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
aa00: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
aa10: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
aa20: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
aa30: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
aa40: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
aa50: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
aa60: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
aa70: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
aa80: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
aa90: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
aaa0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
aab0: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
aac0: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
aad0: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
aae0: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
aaf0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
ab00: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
ab10: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
ab20: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
ab30: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
ab40: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
ab50: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
ab60: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
ab70: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
ab80: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
ab90: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
aba0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
abb0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
abc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
abd0: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
abe0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
abf0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
ac00: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
ac10: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
ac20: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
ac30: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
ac40: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
ac50: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
ac60: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
ac70: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
ac80: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
ac90: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
aca0: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
acb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
acc0: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
acd0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
ace0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
acf0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
ad00: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
ad10: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
ad20: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
ad30: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
ad40: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
ad50: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
ad60: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
ad70: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
ad80: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
ad90: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
ada0: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
adb0: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
adc0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
add0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
ade0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
adf0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
ae00: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
ae10: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
ae20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
ae30: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
ae40: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
ae50: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
ae60: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
ae70: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
ae80: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
ae90: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
aea0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
aeb0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
aec0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
aed0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
aee0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
aef0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
af00: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
af10: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
af20: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
af30: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
af40: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
af50: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
af60: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
af70: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
af80: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
af90: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
afa0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
afb0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
afc0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
afd0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
afe0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
aff0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
b000: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
b010: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
b020: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
b030: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
b040: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
b050: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
b060: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
b070: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
b080: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
b090: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
b0a0: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
b0b0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
b0c0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
b0d0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
b0e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
b0f0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
b100: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
b110: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
b120: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
b130: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
b140: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
b150: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
b160: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
b170: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
b180: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
b190: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
b1a0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b1b0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
b1c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b1d0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
b1e0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
b1f0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
b200: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b210: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
b220: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
b230: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
b240: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
b250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
b260: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
b270: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
b280: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
b290: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b2a0: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
b2b0: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
b2c0: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
b2d0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
b2e0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
b2f0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
b300: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
b310: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
b320: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
b330: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
b340: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
b350: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
b360: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
b370: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
b380: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
b390: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
b3a0: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
b3b0: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
b3c0: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
b3d0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
b3e0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
b3f0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
b400: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
b410: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
b420: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
b430: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
b440: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
b450: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
b460: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
b470: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
b480: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
b490: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
b4a0: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
b4b0: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
b4c0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
b4d0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
b4e0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
b4f0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
b500: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
b510: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
b520: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
b530: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
b540: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
b550: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
b560: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
b570: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
b580: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
b590: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
b5a0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
b5b0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
b5c0: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
b5d0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
b5e0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
b5f0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
b600: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
b610: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
b620: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
b630: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
b640: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
b650: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
b660: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
b670: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
b680: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
b690: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
b6a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
b6b0: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
b6c0: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
b6d0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
b6e0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
b6f0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
b700: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
b710: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
b720: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
b730: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
b740: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
b750: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
b760: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
b770: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
b780: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
b790: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
b7a0: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
b7b0: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
b7c0: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
b7d0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
b7e0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
b7f0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
b800: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
b810: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
b820: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
b830: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
b840: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
b850: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
b860: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
b870: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
b880: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
b890: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
b8a0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
b8b0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
b8c0: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
b8d0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
b8e0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
b8f0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
b900: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
b910: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
b920: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
b930: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
b940: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
b950: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
b960: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
b970: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
b980: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
b990: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
b9a0: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
b9b0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
b9c0: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
b9d0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
b9e0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
b9f0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
ba00: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
ba10: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
ba20: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
ba30: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
ba40: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
ba50: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
ba60: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
ba70: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
ba80: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
ba90: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
baa0: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
bab0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
bac0: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
bad0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
bae0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
baf0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
bb00: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
bb10: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
bb20: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
bb30: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
bb40: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
bb50: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
bb60: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
bb70: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
bb80: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
bb90: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
bba0: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
bbb0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
bbc0: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
bbd0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
bbe0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
bbf0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
bc00: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
bc10: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
bc20: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
bc30: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
bc40: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
bc50: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
bc60: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
bc70: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
bc80: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
bc90: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
bca0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
bcb0: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
bcc0: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
bcd0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
bce0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
bcf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
bd00: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
bd10: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
bd20: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
bd30: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
bd40: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
bd50: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
bd60: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
bd70: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
bd80: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
bd90: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
bda0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
bdb0: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
bdc0: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
bdd0: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
bde0: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
bdf0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
be00: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
be10: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
be20: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
be30: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
be40: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
be50: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
be60: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
be70: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
be80: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
be90: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
bea0: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
beb0: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
bec0: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
bed0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
bee0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
bef0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
bf00: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
bf10: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
bf20: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
bf30: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
bf40: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
bf50: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
bf60: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
bf70: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
bf80: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
bf90: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
bfa0: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
bfb0: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
bfc0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
bfd0: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
bfe0: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
bff0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
c000: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
c010: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
c020: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
c030: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
c040: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
c050: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
c060: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
c070: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
c080: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
c090: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
c0a0: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
c0b0: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
c0c0: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
c0d0: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
c0e0: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
c0f0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
c100: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
c110: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
c120: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
c130: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
c140: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
c150: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
c160: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
c170: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
c180: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
c190: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
c1a0: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
c1b0: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
c1c0: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
c1d0: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
c1e0: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
c1f0: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
c200: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
c210: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
c220: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
c230: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
c240: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
c250: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
c260: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
c270: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
c280: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
c290: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
c2a0: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
c2b0: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
c2c0: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
c2d0: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
c2e0: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
c2f0: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
c300: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
c310: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
c320: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
c330: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
c340: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
c350: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
c360: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
c370: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
c380: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
c390: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
c3a0: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
c3b0: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
c3c0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
c3d0: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
c3e0: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
c3f0: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
c400: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
c410: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
c420: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
c430: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
c440: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
c450: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
c460: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
c470: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
c480: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
c490: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
c4a0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
c4b0: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
c4c0: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
c4d0: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
c4e0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
c4f0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
c500: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
c510: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
c520: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
c530: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
c540: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
c550: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
c560: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
c570: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
c580: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
c590: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
c5a0: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
c5b0: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
c5c0: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
c5d0: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
c5e0: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
c5f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
c600: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
c610: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
c620: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
c630: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
c640: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
c650: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
c660: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
c670: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
c680: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
c690: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
c6a0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
c6b0: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
c6c0: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
c6d0: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
c6e0: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
c6f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c700: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c710: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
c720: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
c730: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c740: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c750: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
c760: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
c770: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
c780: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c790: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c7a0: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
c7b0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
c7c0: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
c7d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
c7e0: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
c7f0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
c800: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
c810: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
c820: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
c830: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
c840: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
c850: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
c860: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
c870: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
c880: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
c890: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
c8a0: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
c8b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
c8c0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
c8d0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
c8e0: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
c8f0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
c900: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
c910: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
c920: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
c930: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
c940: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
c950: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
c960: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
c970: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
c980: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
c990: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
c9a0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
c9b0: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
c9c0: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
c9d0: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
c9e0: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
c9f0: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
ca00: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
ca10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ca20: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
ca30: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
ca40: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
ca50: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
ca60: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
ca70: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
ca80: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
ca90: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
caa0: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
cab0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
cac0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
cad0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
cae0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
caf0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
cb00: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
cb10: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
cb20: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
cb30: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
cb40: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
cb50: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
cb60: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
cb70: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
cb80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
cb90: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
cba0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
cbb0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
cbc0: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
cbd0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
cbe0: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
cbf0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
cc00: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
cc10: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
cc20: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
cc30: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
cc40: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
cc50: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
cc60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
cc70: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
cc80: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
cc90: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
cca0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
ccb0: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
ccc0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
ccd0: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
cce0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
ccf0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
cd00: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
cd10: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
cd20: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
cd30: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
cd40: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
cd50: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
cd60: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
cd70: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
cd80: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
cd90: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
cda0: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
cdb0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
cdc0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
cdd0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
cde0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
cdf0: 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
ce00: 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
ce10: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
ce20: 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
ce30: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
ce40: 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
ce50: 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
ce60: 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
ce70: 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
ce80: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
ce90: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
cea0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
ceb0: 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
cec0: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
ced0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
cee0: 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
cef0: 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
cf00: 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
cf10: 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
cf20: 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
cf30: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
cf40: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
cf50: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
cf60: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
cf70: 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
cf80: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
cf90: 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
cfa0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
cfb0: 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
cfc0: 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
cfd0: 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
cfe0: 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
cff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d000: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
d010: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
d020: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
d030: 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
d040: 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
d050: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
d060: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d070: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
d080: 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
d090: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
d0a0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
d0b0: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
d0c0: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
d0d0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
d0e0: 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
d0f0: 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
d100: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
d110: 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
d120: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
d130: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d140: 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
d150: 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
d160: 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
d170: 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
d180: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
d190: 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
d1a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
d1b0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
d1c0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
d1d0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
d1e0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
d1f0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
d200: 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
d210: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
d220: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
d230: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
d240: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
d250: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
d260: 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
d270: 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
d280: 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
d290: 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
d2a0: 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
d2b0: 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
d2c0: 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72  given no the cor
d2d0: 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
d2e0: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
d2f0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
d300: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
d310: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
d320: 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
d330: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
d340: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
d350: 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
d360: 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
d370: 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
d380: 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
d390: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
d3a0: 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
d3b0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
d3c0: 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
d3d0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
d3e0: 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
d3f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
d400: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
d410: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d420: 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
d430: 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
d440: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
d450: 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
d460: 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
d470: 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
d480: 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
d490: 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
d4a0: 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
d4b0: 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
d4c0: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
d4d0: 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
d4e0: 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
d4f0: 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
d500: 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
d510: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
d520: 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
d530: 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
d540: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
d550: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
d560: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
d570: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d580: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
d590: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
d5a0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
d5b0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
d5c0: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
d5d0: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
d5e0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
d5f0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
d600: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
d610: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
d620: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
d630: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
d640: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
d650: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
d660: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
d670: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
d680: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
d690: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
d6a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
d6b0: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
d6c0: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
d6d0: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
d6e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
d6f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
d700: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
d710: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
d720: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
d730: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
d740: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
d750: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
d760: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
d770: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
d780: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
d790: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
d7a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
d7b0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
d7c0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
d7d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
d7e0: 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
d7f0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
d800: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
d810: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
d820: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
d830: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
d840: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
d850: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
d860: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
d870: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d880: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
d890: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
d8a0: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
d8b0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
d8c0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
d8d0: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
d8e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
d8f0: 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
d900: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
d910: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d920: 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
d930: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
d940: 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
d950: 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
d960: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
d970: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
d980: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
d990: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d9a0: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
d9b0: 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
d9c0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d9d0: 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
d9e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
d9f0: 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
da00: 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
da10: 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
da20: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
da30: 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
da40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
da50: 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
da60: 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
da70: 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
da80: 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
da90: 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
daa0: 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
dab0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
dac0: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
dad0: 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
dae0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
daf0: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
db00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
db10: 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
db20: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
db30: 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
db40: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
db50: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
db60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
db70: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
db80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
db90: 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
dba0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
dbb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
dbc0: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
dbd0: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
dbe0: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
dbf0: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
dc00: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
dc10: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
dc20: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
dc30: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
dc40: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
dc50: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
dc60: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
dc70: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
dc80: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
dc90: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
dca0: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
dcb0: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
dcc0: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
dcd0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
dce0: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
dcf0: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
dd00: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
dd10: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
dd20: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
dd30: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
dd40: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
dd50: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
dd60: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
dd70: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
dd80: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
dd90: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
dda0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
ddb0: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
ddc0: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
ddd0: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
dde0: 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
ddf0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
de00: 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
de10: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
de20: 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
de30: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
de40: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
de50: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
de60: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
de70: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
de80: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
de90: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
dea0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
deb0: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
dec0: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
ded0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
dee0: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
def0: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
df00: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
df10: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
df20: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
df30: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
df40: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
df50: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
df60: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
df70: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
df80: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
df90: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
dfa0: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
dfb0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
dfc0: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
dfd0: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
dfe0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
dff0: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
e000: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
e010: 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
e020: 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
e030: 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
e040: 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
e050: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
e060: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e070: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
e080: 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
e090: 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
e0a0: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
e0b0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
e0c0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
e0d0: 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
e0e0: 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
e0f0: 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
e100: 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
e110: 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
e120: 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
e130: 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
e140: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
e150: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
e160: 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
e170: 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
e180: 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
e190: 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
e1a0: 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
e1b0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
e1c0: 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
e1d0: 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
e1e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
e1f0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
e200: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
e210: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
e220: 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
e230: 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
e240: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
e250: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
e260: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
e270: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
e280: 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
e290: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
e2a0: 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
e2b0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
e2c0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
e2d0: 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
e2e0: 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
e2f0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
e300: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e310: 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
e320: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
e330: 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
e340: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
e350: 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
e360: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
e370: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e380: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
e390: 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
e3a0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
e3b0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
e3c0: 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
e3d0: 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
e3e0: 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
e3f0: 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
e400: 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
e410: 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
e420: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
e430: 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
e440: 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
e450: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
e460: 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
e470: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
e480: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
e490: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
e4a0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
e4b0: 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
e4c0: 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
e4d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
e4e0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
e4f0: 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
e500: 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
e510: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
e520: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
e530: 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
e540: 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
e550: 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51  * failure..*/.SQ
e560: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
e570: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e580: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
e590: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  I int sqlite3_sh
e5a0: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51  utdown(void);.SQ
e5b0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
e5c0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
e5d0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
e5e0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
e5f0: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
e600: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
e610: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
e620: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
e630: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
e640: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
e650: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
e660: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
e670: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
e680: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
e690: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
e6a0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
e6b0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
e6c0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
e6d0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
e6e0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
e6f0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
e700: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
e710: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
e720: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
e730: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
e740: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
e750: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
e760: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
e770: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
e780: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
e790: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
e7a0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
e7b0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
e7c0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
e7d0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
e7e0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
e7f0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
e800: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
e810: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
e820: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e830: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
e840: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
e850: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
e860: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
e870: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
e880: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
e890: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
e8a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e8b0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
e8c0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
e8d0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
e8e0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
e8f0: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
e900: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
e910: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
e920: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
e930: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
e940: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
e950: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
e960: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
e970: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
e980: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
e990: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
e9a0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
e9b0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
e9c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
e9d0: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
e9e0: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
e9f0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
ea00: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
ea10: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
ea20: 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
ea30: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
ea40: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
ea50: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
ea60: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
ea70: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
ea80: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
ea90: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
eaa0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
eab0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
eac0: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
ead0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
eae0: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
eaf0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
eb00: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
eb10: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
eb20: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
eb30: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
eb40: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
eb50: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
eb60: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
eb70: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
eb80: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
eb90: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
eba0: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49  r code]..*/.SQLI
ebb0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
ebc0: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
ebd0: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
ebe0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
ebf0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ec00: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
ec10: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ec20: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
ec30: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
ec40: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
ec50: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
ec60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ec70: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
ec80: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
ec90: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
eca0: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
ecb0: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
ecc0: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
ecd0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
ece0: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
ecf0: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
ed00: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
ed10: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
ed20: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
ed30: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
ed40: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
ed50: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
ed60: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
ed70: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
ed80: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
ed90: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
eda0: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
edb0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
edc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
edd0: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
ede0: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
edf0: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
ee00: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ee10: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
ee20: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
ee30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
ee40: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
ee50: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
ee60: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
ee70: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
ee80: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
ee90: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
eea0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
eeb0: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
eec0: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
eed0: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
eee0: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
eef0: 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
ef00: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
ef10: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
ef20: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
ef30: 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
ef40: 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
ef50: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
ef60: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
ef70: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
ef80: 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
ef90: 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
efa0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
efb0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
efc0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
efd0: 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
efe0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
eff0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f000: 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
f010: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
f020: 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
f030: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
f040: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
f050: 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
f060: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
f070: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
f080: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
f090: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
f0a0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
f0b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
f0c0: 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
f0d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
f0e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
f0f0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
f100: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
f110: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
f120: 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
f130: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
f140: 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
f150: 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
f160: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
f170: 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
f180: 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
f190: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
f1a0: 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
f1b0: 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
f1c0: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
f1d0: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
f1e0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
f1f0: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
f200: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
f210: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
f220: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
f230: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
f240: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
f250: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
f260: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
f270: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
f280: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
f290: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
f2a0: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
f2b0: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
f2c0: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
f2d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
f2e0: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
f2f0: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
f300: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
f310: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
f320: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
f330: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
f340: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
f350: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
f360: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
f370: 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
f380: 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
f390: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
f3a0: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
f3b0: 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
f3c0: 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
f3d0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
f3e0: 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
f3f0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
f400: 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
f410: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
f420: 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
f430: 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
f440: 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
f450: 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
f460: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
f470: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
f480: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
f490: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f4a0: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
f4b0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
f4c0: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
f4d0: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
f4e0: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
f4f0: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
f500: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
f510: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
f520: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
f530: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
f540: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
f550: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
f560: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
f570: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
f580: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
f590: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
f5a0: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
f5b0: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
f5c0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
f5d0: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
f5e0: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
f5f0: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
f600: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
f610: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
f620: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
f630: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
f640: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
f650: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
f660: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
f670: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
f680: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
f690: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
f6a0: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
f6b0: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
f6c0: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
f6d0: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
f6e0: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
f6f0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
f700: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f710: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
f720: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
f730: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
f740: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f750: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
f760: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
f770: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
f780: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
f790: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
f7a0: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
f7b0: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
f7c0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
f7d0: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
f7e0: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
f7f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
f800: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
f810: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
f820: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
f830: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
f840: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
f850: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
f860: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
f870: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
f880: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
f890: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
f8a0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
f8b0: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
f8c0: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
f8d0: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
f8e0: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
f8f0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
f900: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
f910: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
f920: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
f930: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
f940: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
f950: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
f960: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
f970: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
f980: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
f990: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
f9a0: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
f9b0: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
f9c0: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
f9d0: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
f9e0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
f9f0: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
fa00: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
fa10: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
fa20: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
fa30: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
fa40: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
fa50: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
fa60: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
fa70: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
fa80: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
fa90: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
faa0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
fab0: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
fac0: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
fad0: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
fae0: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
faf0: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
fb00: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
fb10: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
fb20: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
fb30: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
fb40: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
fb50: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
fb60: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
fb70: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
fb80: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
fb90: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
fba0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
fbb0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
fbc0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
fbd0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
fbe0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
fbf0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
fc00: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
fc10: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
fc20: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
fc30: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
fc40: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
fc50: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
fc60: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
fc70: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
fc80: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
fc90: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
fca0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
fcb0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
fcc0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
fcd0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
fce0: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
fcf0: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
fd00: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
fd10: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
fd20: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
fd30: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
fd40: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
fd50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
fd60: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
fd70: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
fd80: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
fd90: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
fda0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
fdb0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
fdc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
fdd0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
fde0: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
fdf0: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
fe00: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
fe10: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
fe20: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
fe30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fe40: 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
fe50: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
fe60: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
fe70: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
fe80: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
fe90: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
fea0: 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
feb0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
fec0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fed0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
fee0: 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
fef0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
ff00: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
ff10: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
ff20: 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
ff30: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
ff40: 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
ff50: 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
ff60: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
ff70: 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
ff80: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
ff90: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
ffa0: 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
ffb0: 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
ffc0: 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
ffd0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
ffe0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
fff0: 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
10000 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
10010 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
10020 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
10030 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
10040 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
10050 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
10060 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
10070 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
10080 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
10090 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
100a0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
100b0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
100c0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
100d0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
100e0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
100f0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
10100 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
10110 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
10120 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
10130 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
10140 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
10150 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
10160 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
10170 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
10180 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
10190 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
101a0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
101b0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
101c0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
101d0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
101e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
101f0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
10200 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
10210 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
10220 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
10230 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
10240 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
10250 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
10260 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10270 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
10280 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
10290 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
102a0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
102b0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
102c0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
102d0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
102e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
102f0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
10300 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10310 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
10320 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
10330 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
10340 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
10350 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
10360 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
10370 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
10380 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
10390 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
103a0 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
103b0 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
103c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
103d0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
103e0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
103f0 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
10400 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
10410 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
10420 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
10430 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
10440 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
10450 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
10460 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
10470 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
10480 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
10490 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
104a0 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
104b0 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
104c0 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
104d0 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
104e0 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
104f0 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
10500 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10510 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
10520 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
10530 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10540 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
10550 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
10560 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
10570 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
10580 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
10590 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
105a0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
105b0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
105c0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
105d0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
105e0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
105f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
10600 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
10610 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
10620 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
10630 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
10640 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
10650 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10660 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
10670 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10680 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
10690 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
106a0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
106b0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
106c0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
106d0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
106e0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
106f0 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
10700 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
10710 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
10720 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
10730 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
10740 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
10750 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
10760 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
10770 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
10780 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
10790 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
107a0 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
107b0 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
107c0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
107d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
107e0 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
107f0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
10800 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
10810 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
10820 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10830 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
10840 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
10850 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
10860 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
10870 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
10880 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
10890 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
108a0 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
108b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
108c0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
108d0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
108e0 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
108f0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10900 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10910 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10920 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10930 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10940 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10950 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
10960 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
10970 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
10980 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
10990 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
109a0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
109b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
109c0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
109d0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
109e0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
109f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10a00 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
10a10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10a20 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
10a30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10a40 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
10a50 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
10a60 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
10a70 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
10a80 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
10a90 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
10aa0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
10ab0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
10ac0 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
10ad0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
10ae0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
10af0 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
10b00 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
10b10 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
10b20 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
10b30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
10b40 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
10b50 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
10b60 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
10b70 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
10b80 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
10b90 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
10ba0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
10bb0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
10bc0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
10bd0 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
10be0 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
10bf0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10c00 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
10c10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10c20 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
10c30 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
10c40 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
10c50 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
10c60 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
10c70 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
10c80 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
10c90 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
10ca0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
10cb0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
10cc0 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
10cd0 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
10ce0 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
10cf0 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
10d00 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
10d10 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
10d20 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
10d30 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
10d40 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
10d50 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
10d60 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
10d70 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
10d80 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
10d90 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
10da0 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
10db0 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
10dc0 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
10dd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10de0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
10df0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10e00 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
10e10 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
10e20 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
10e30 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
10e40 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
10e50 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f  eted as a .** bo
10e60 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
10e70 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
10e80 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
10e90 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
10ea0 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74  tion .** statist
10eb0 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
10ec0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
10ed0 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
10ee0 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66  abled, the .** f
10ef0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
10f00 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
10f10 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
10f20 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
10f30 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
10f40 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
10f50 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
10f60 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
10f70 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
10f80 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
10f90 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
10fa0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
10fb0 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
10fc0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
10fd0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
10fe0 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
10ff0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
11000 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
11010 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
11020 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
11030 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
11040 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
11050 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
11060 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
11070 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
11080 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
11090 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
110a0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
110b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
110c0 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
110d0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
110e0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
110f0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
11100 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
11110 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73  can use for.** s
11120 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
11130 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
11140 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f  arguments:  A po
11150 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
11160 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
11170 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
11180 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20  ich the scratch 
11190 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
111a0 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
111b0 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
111c0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
111d0 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
111e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
111f0 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
11200 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54  ocations (N).  T
11210 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
11220 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
11230 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54  iple of 16..** T
11240 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11250 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
11260 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
11270 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
11280 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
11290 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
112a0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
112b0 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
112c0 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63   than two scratc
112d0 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
112e0 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73  read.  So.** N s
112f0 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
11300 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74  twice the expect
11310 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
11320 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a  r of threads..**
11330 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
11340 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
11350 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
11360 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
11370 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
11380 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
11390 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
113a0 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
113b0 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
113c0 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
113d0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
113e0 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
113f0 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
11400 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
11410 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
11420 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
11430 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
11440 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11450 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
11460 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  ECACHE]] <dt>SQL
11470 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
11480 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
11490 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
114a0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
114b0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
114c0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
114d0 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
114e0 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
114f0 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
11500 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
11510 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
11520 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
11530 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  ration should no
11540 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20  t be used if an 
11550 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
11560 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
11570 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11580 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
11590 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
115a0 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  G_PCACHE2 option
115b0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
115c0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
115d0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41  o this option: A
115e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79   pointer to 8-by
115f0 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
11600 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
11610 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
11620 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
11630 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
11640 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
11650 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
11660 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
11670 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
11680 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
11690 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
116a0 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
116b0 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65  8) plus a little
116c0 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a   extra for each.
116d0 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
116e0 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65   ^The page heade
116f0 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20  r size is 20 to 
11700 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69  40 bytes dependi
11710 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73  ng on.** the hos
11720 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20  t architecture. 
11730 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
11740 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
11750 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
11760 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
11770 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
11780 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
11790 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
117a0 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
117b0 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
117c0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
117d0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
117e0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
117f0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
11800 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
11810 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
11820 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
11830 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
11840 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
11850 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
11860 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
11870 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
11880 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
11890 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
118a0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
118b0 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
118c0 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
118d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
118e0 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
118f0 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
11900 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69  pace..** The poi
11910 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  nter in the firs
11920 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a  t argument must.
11930 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  ** be aligned to
11940 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
11950 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
11960 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
11970 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  Lite.** will be 
11980 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
11990 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
119a0 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74  ONFIG_HEAP]] <dt
119b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
119c0 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
119d0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
119e0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
119f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
11a00 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
11a10 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
11a20 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
11a30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11a40 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
11a50 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
11a60 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
11a70 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
11a80 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
11a90 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
11aa0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
11ab0 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
11ac0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
11ad0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
11ae0 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
11af0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
11b00 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
11b10 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
11b20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
11b30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
11b40 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
11b50 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
11b60 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
11b70 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
11b80 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
11b90 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
11ba0 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
11bb0 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
11bc0 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
11bd0 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
11be0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
11bf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11c00 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
11c10 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
11c20 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
11c30 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
11c40 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
11c50 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
11c60 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
11c70 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
11c80 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
11c90 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
11ca0 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
11cb0 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
11cc0 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
11cd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
11ce0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
11cf0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
11d00 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
11d10 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
11d20 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
11d30 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
11d40 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
11d50 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
11d60 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
11d70 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
11d80 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
11d90 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
11da0 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
11db0 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
11dc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
11dd0 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
11de0 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
11df0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11e00 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
11e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
11e20 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
11e30 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
11e40 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
11e50 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
11e60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
11e70 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
11e80 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
11e90 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
11ea0 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
11eb0 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
11ec0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
11ed0 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
11ee0 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
11ef0 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
11f00 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
11f10 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
11f20 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
11f30 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
11f40 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  .** content of t
11f50 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
11f60 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
11f70 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
11f80 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
11f90 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
11fa0 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
11fb0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11fc0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11fd0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11fe0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11ff0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12000 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12010 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
12020 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
12030 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
12040 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
12050 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
12060 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12070 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
12080 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
12090 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
120a0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
120b0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
120c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
120d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
120e0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
120f0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
12100 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
12110 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
12120 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12130 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12140 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12150 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
12160 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
12170 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12180 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
12190 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
121a0 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
121b0 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
121c0 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
121d0 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
121e0 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
121f0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
12200 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
12210 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
12220 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
12230 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
12240 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
12250 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
12260 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
12270 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
12280 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
12290 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
122a0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
122b0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
122c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
122d0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
122e0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
122f0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12300 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
12310 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
12320 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
12330 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
12340 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
12350 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12360 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
12370 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
12380 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
12390 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
123a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
123b0 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
123c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
123d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
123e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
123f0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
12400 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12410 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
12420 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
12430 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
12440 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
12450 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68  llocation for th
12460 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
12470 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20  ry allocator on 
12480 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
12490 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
124a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
124b0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
124c0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
124d0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
124e0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
124f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
12500 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
12510 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
12520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
12530 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  ^  ^(This option
12540 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e   sets the.** <i>
12550 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
12560 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
12570 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
12580 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76  _LOOKASIDE].** v
12590 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  erb to [sqlite3_
125a0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
125b0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
125c0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
125d0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
125e0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
125f0 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
12600 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12610 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12620 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
12630 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
12640 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12650 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12660 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12670 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12680 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73  nter to.** an [s
12690 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
126a0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
126b0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
126c0 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72  cifies the inter
126d0 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73  face.** to a cus
126e0 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
126f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
12700 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
12710 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
12720 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
12730 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
12740 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12750 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
12760 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12770 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
12780 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12790 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
127a0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
127b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
127c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
127d0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
127e0 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
127f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
12800 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
12810 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74  Lite copies of t
12820 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61  he current.** pa
12830 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
12840 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
12850 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
12860 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12870 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
12880 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12890 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
128a0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
128b0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
128c0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
128d0 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
128e0 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
128f0 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
12900 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
12910 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
12920 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
12930 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
12940 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
12950 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
12960 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
12970 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
12980 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
12990 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
129a0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
129b0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
129c0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
129d0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
129e0 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
129f0 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
12a00 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
12a10 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
12a20 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12a30 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
12a40 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
12a50 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
12a60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12a70 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
12a80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
12a90 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
12aa0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
12ab0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
12ac0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
12ad0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
12ae0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
12af0 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
12b00 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
12b10 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
12b20 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
12b30 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
12b40 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
12b50 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
12b60 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
12b70 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
12b80 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
12b90 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
12ba0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
12bb0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
12bc0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
12bd0 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
12be0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
12bf0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
12c00 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
12c10 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
12c20 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
12c30 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
12c40 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
12c50 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
12c60 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
12c70 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
12c80 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
12c90 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
12ca0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
12cb0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
12cc0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
12cd0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
12ce0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
12d00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12d10 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20  FIG_URI.** <dd> 
12d20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12d30 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12d40 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
12d50 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   If non-zero, th
12d60 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69  en.** URI handli
12d70 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
12d80 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
12d90 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
12da0 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
12db0 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c  ing.** is global
12dc0 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20  ly disabled. If 
12dd0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
12de0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
12df0 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a  , all filenames.
12e00 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  ** passed to [sq
12e10 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
12e20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
12e30 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
12e40 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
12e50 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
12e60 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
12e70 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
12e80 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
12e90 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
12ea0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
12eb0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
12ec0 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
12ed0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
12ee0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
12ef0 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20  s opened. If it 
12f00 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
12f10 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
12f20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
12f30 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
12f40 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
12f50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
12f60 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
12f70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12f80 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79  on is opened. By
12f90 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61   default, URI ha
12fa0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
12fb0 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20  ly.** disabled. 
12fc0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
12fd0 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64  e may be changed
12fe0 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69   by compiling wi
12ff0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
13000 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f  E_USE_URI] symbo
13010 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  l defined..**.**
13020 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13030 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
13040 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13050 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
13060 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13070 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
13080 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
13090 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
130a0 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
130b0 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
130c0 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
130d0 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
130e0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
130f0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
13100 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
13110 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
13120 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
13130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13140 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
13150 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
13160 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13170 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
13180 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
13190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
131a0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
131b0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
131c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
131d0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
131e0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
131f0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
13200 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13210 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
13220 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
13230 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
13240 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13250 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
13260 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
13270 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
13280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13290 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
132a0 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
132b0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
132c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
132d0 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
132e0 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
132f0 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
13300 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
13310 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13320 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
13330 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
13340 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13350 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
13360 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
13370 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
13380 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13390 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
133a0 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
133b0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
133c0 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
133d0 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
133e0 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
133f0 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
13400 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
13410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13420 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
13430 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
13440 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13450 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
13460 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
13470 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13480 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
13490 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
134a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
134b0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
134c0 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
134d0 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
134e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
134f0 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
13500 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
13510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13520 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
13530 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
13540 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
13550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13560 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13570 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
13580 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13590 68 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  hods2* */../*.**
135a0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
135b0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
135c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
135d0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
135e0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
135f0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
13600 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
13610 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
13620 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
13630 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
13640 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
13650 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
13660 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
13670 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
13680 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
13690 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
136a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
136b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
136c0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
136d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
136e0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
136f0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
13700 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
13710 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
13720 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
13730 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
13740 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
13750 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
13760 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
13770 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
13780 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
13790 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
137a0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
137b0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
137c0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
137d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
137e0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
137f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
13800 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
13810 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13820 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13830 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13840 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
13850 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
13860 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
13870 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
13880 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
13890 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
138a0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
138b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
138c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
138d0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
138e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
138f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
13900 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
13910 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
13920 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
13930 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
13940 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
13950 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
13960 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
13970 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
13980 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
13990 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
139a0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
139b0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
139c0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
139d0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
139e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
139f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
13a00 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
13a10 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
13a20 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
13a30 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
13a40 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
13a50 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
13a60 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
13a70 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
13a80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13a90 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
13aa0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
13ab0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
13ac0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
13ad0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
13ae0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
13af0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
13b00 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
13b10 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
13b20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
13b30 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
13b40 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
13b50 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
13b60 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
13b70 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
13b80 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
13b90 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
13ba0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
13bb0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
13bc0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
13bd0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
13be0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
13bf0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
13c00 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
13c10 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
13c20 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
13c30 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
13c40 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
13c50 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
13c60 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
13c70 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
13c80 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
13c90 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
13ca0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13cb0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
13cc0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
13cd0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
13ce0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
13cf0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
13d00 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
13d10 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
13d20 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
13d30 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
13d40 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
13d50 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
13d60 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
13d70 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
13d80 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
13d90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
13da0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
13db0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
13dc0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
13dd0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
13de0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
13df0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
13e00 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
13e10 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
13e20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
13e30 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
13e40 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
13e50 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
13e60 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
13e70 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
13e80 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
13e90 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
13ea0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
13eb0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
13ec0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
13ed0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
13ee0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
13ef0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
13f00 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
13f10 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
13f20 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
13f30 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
13f40 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
13f50 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
13f60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13f70 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
13f80 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
13f90 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
13fa0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
13fb0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
13fc0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
13fd0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
13fe0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
13ff0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
14000 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
14010 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
14020 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
14030 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
14040 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
14050 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
14060 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
14070 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
14080 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
14090 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
140a0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
140b0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
140c0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
140d0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
140e0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
140f0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
14100 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
14110 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14120 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14130 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
14140 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
14150 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
14160 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
14170 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
14180 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
14190 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
141a0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
141b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
141c0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
141d0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
141e0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
141f0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
14200 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
14210 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
14220 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
14230 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14240 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
14250 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
14260 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
14270 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
14280 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
14290 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
142a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
142b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
142c0 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
142d0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
142e0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
142f0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
14300 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
14310 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
14320 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
14330 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
14340 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
14350 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
14360 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
14370 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
14380 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
14390 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
143a0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
143b0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
143c0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
143d0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
143e0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
143f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
14400 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
14410 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
14420 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
14430 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
14440 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
14450 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
14460 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
14470 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
14480 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
14490 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
144a0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
144b0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
144c0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
144d0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
144e0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
144f0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
14500 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
14510 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
14520 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
14530 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
14540 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
14550 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
14560 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
14570 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
14580 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
14590 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
145a0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
145b0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
145c0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
145d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
145e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
145f0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
14600 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
14610 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
14620 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
14630 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
14640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14650 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
14660 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
14670 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
14680 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73  sion 3.7.7, this
14690 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63   routines.** rec
146a0 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e  ords the last in
146b0 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f  sert rowid of bo
146c0 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c  th ordinary tabl
146d0 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20  es and [virtual 
146e0 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20  tables]..** ^If 
146f0 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
14700 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
14710 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
14720 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
14730 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
14740 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
14750 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
14760 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
14770 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
14780 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
14790 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
147a0 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
147b0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
147c0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
147d0 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
147e0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
147f0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
14800 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
14810 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
14820 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
14830 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
14840 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
14850 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
14860 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
14870 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
14880 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
14890 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
148a0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
148b0 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
148c0 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
148d0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
148e0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
148f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
14900 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
14910 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
14920 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
14930 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
14940 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
14950 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
14960 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
14970 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
14980 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
14990 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
149a0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
149b0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
149c0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
149d0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
149e0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
149f0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
14a00 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
14a10 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
14a20 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
14a30 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
14a40 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
14a50 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
14a60 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
14a70 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
14a80 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
14a90 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
14aa0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
14ab0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
14ac0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
14ad0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
14ae0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
14af0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
14b00 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
14b10 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
14b20 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
14b30 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
14b40 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
14b50 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
14b60 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
14b70 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
14b80 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
14b90 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
14ba0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
14bb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
14bc0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
14bd0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
14be0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
14bf0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
14c00 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
14c10 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
14c20 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
14c30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14c40 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
14c50 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
14c60 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
14c70 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
14c80 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
14c90 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
14ca0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
14cb0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
14cc0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
14cd0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
14ce0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
14cf0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
14d00 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
14d10 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
14d20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
14d30 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
14d40 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
14d50 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
14d60 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
14d70 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
14d80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
14d90 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
14da0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
14db0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
14dc0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
14dd0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
14de0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
14df0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
14e00 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
14e10 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
14e20 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
14e30 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
14e40 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
14e50 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
14e60 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
14e70 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
14e80 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
14e90 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
14ea0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
14eb0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
14ec0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
14ed0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
14ee0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
14ef0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
14f00 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
14f10 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
14f20 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
14f30 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
14f40 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
14f50 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
14f60 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
14f70 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
14f80 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
14f90 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
14fa0 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
14fb0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
14fc0 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
14fd0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
14fe0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
14ff0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
15000 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
15010 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
15020 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
15030 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
15040 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
15050 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
15060 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
15070 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
15080 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
15090 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
150a0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
150b0 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
150c0 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
150d0 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
150e0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
150f0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
15100 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
15110 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
15120 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
15130 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
15140 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
15150 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
15160 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
15170 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
15180 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
15190 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
151a0 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
151b0 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
151c0 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
151d0 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
151e0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
151f0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
15200 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
15210 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
15220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
15230 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
15240 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
15250 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
15260 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
15270 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
15280 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
15290 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
152a0 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
152b0 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
152c0 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
152d0 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
152e0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
152f0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
15300 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
15310 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
15320 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
15330 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
15340 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
15350 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
15360 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
15370 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
15380 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
15390 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
153a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
153b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
153c0 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
153d0 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
153e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
153f0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
15400 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
15410 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
15420 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
15430 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
15440 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
15450 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
15460 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
15470 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
15480 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
15490 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
154a0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
154b0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
154c0 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
154d0 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
154e0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
154f0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
15500 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
15510 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
15520 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
15530 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
15540 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
15550 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
15560 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
15570 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
15580 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
15590 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
155a0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
155b0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
155c0 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
155d0 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
155e0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
155f0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
15600 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
15610 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
15620 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
15630 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
15640 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
15650 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
15660 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
15670 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
15680 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
15690 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
156a0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
156b0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
156c0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
156d0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
156e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
156f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
15700 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
15710 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
15720 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
15730 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
15740 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
15750 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
15760 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
15770 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
15780 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
15790 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
157a0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
157b0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
157c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
157d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
157e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
157f0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
15800 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
15810 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
15820 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
15830 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
15840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
15850 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
15860 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
15870 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
15880 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
15890 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
158a0 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
158b0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
158c0 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
158d0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
158e0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
158f0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
15900 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
15910 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
15920 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
15930 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
15940 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
15950 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
15960 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
15970 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
15980 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
15990 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
159a0 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
159b0 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
159c0 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
159d0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
159e0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
159f0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
15a00 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
15a10 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
15a20 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
15a30 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
15a40 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
15a50 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
15a60 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
15a70 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
15a80 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
15a90 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
15aa0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
15ab0 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
15ac0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
15ad0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
15ae0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
15af0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
15b00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
15b10 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
15b20 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
15b30 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
15b40 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
15b50 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
15b60 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
15b70 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
15b80 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
15b90 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
15ba0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
15bb0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
15bc0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
15bd0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
15be0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
15bf0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
15c00 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
15c10 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
15c20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
15c30 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
15c40 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
15c50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
15c60 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
15c70 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
15c80 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
15c90 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
15ca0 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
15cb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
15cc0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
15cd0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
15ce0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
15cf0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
15d00 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
15d10 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
15d20 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
15d30 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
15d40 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
15d50 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
15d60 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
15d70 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
15d80 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
15d90 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
15da0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
15db0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
15dc0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
15dd0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
15de0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
15df0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
15e00 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
15e10 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
15e20 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
15e30 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
15e40 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
15e50 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
15e60 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
15e70 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
15e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
15e90 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
15ea0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
15eb0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
15ec0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
15ed0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
15ee0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
15ef0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
15f00 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
15f10 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
15f20 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
15f30 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
15f40 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
15f50 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
15f60 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
15f70 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
15f80 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
15f90 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
15fa0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
15fb0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
15fc0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
15fd0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
15fe0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
15ff0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
16000 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
16010 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
16020 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
16030 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
16040 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
16050 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
16060 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
16070 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
16080 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
16090 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
160a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
160b0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
160c0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
160d0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
160e0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
160f0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
16100 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
16110 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
16120 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
16130 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
16140 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
16150 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
16160 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
16170 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
16180 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
16190 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
161a0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
161b0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
161c0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
161d0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
161e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
161f0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
16200 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
16210 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
16220 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
16230 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
16240 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
16250 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
16260 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
16270 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
16280 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
16290 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
162a0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
162b0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
162c0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
162d0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
162e0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
162f0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
16300 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
16310 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
16320 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
16330 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
16340 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
16350 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
16360 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
16370 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
16380 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
16390 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
163a0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
163b0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53  ely happen..*/.S
163c0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
163d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
163e0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
163f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
16400 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
16410 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
16420 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
16430 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
16440 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
16450 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
16460 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
16470 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
16480 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
16490 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
164a0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
164b0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
164c0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
164d0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
164e0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
164f0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
16500 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
16510 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
16520 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
16530 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
16540 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
16550 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
16560 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
16570 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
16580 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
16590 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
165a0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
165b0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
165c0 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
165d0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
165e0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
165f0 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
16600 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
16610 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
16620 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
16630 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
16640 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
16650 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
16660 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
16670 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
16680 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
16690 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
166a0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
166b0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
166c0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
166d0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
166e0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
166f0 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
16700 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
16710 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
16720 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
16730 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
16740 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
16750 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
16760 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
16770 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
16780 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
16790 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
167a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
167b0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
167c0 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
167d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
167e0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
167f0 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
16800 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
16810 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
16820 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
16830 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
16840 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
16850 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
16860 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
16870 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
16880 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
16890 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
168a0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
168b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
168c0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
168d0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
168e0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
168f0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
16900 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
16910 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
16920 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
16930 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
16940 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
16950 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
16960 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
16970 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
16980 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
16990 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
169a0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
169b0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
169c0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
169d0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
169e0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
169f0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
16a00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
16a10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
16a20 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
16a30 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  der..*/.SQLITE_A
16a40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
16a50 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
16a60 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
16a70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
16a80 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
16a90 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
16aa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
16ab0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
16ac0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
16ad0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
16ae0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
16af0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
16b00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
16b10 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
16b20 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
16b30 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
16b40 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
16b50 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
16b60 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
16b70 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
16b80 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
16b90 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
16ba0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
16bb0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
16bc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
16bd0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
16be0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
16bf0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
16c00 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
16c10 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
16c20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
16c30 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
16c40 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
16c50 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
16c60 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
16c70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
16c80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
16c90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
16ca0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
16cb0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
16cc0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
16cd0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
16ce0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
16cf0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
16d00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
16d10 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
16d20 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
16d30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
16d40 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
16d50 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
16d60 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
16d70 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
16d80 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
16d90 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
16da0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
16db0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
16dc0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
16dd0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
16de0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
16df0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
16e00 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
16e10 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
16e20 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
16e30 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
16e40 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
16e50 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
16e60 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
16e70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
16e80 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
16e90 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
16ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
16eb0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
16ec0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
16ed0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
16ee0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
16ef0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
16f00 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
16f10 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
16f20 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
16f30 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
16f40 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
16f50 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
16f60 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
16f70 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
16f80 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
16f90 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
16fa0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
16fb0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
16fc0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
16fd0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
16fe0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
16ff0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
17000 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
17010 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
17020 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
17030 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
17040 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
17050 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
17060 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
17070 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
17080 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
17090 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
170a0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
170b0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
170c0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
170d0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
170e0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
170f0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
17100 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
17110 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
17120 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
17130 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
17140 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
17150 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
17160 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
17170 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
17180 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
17190 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
171a0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
171b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
171c0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
171d0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
171e0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
171f0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
17200 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
17210 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
17220 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
17230 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
17240 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
17250 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
17260 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
17270 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
17280 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
17290 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
172a0 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
172b0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
172c0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
172d0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
172e0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
172f0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
17300 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
17310 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
17320 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
17330 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
17340 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
17350 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
17360 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
17370 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
17380 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
17390 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
173a0 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
173b0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
173c0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
173d0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
173e0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
173f0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
17400 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
17410 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
17420 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
17430 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
17440 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
17450 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
17460 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
17470 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
17480 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
17490 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
174a0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
174b0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
174c0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
174d0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
174e0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
174f0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
17500 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
17510 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
17520 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
17530 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
17540 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
17550 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
17560 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
17570 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
17580 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
17590 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
175a0 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
175b0 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
175c0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
175d0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
175e0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
175f0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
17600 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
17610 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
17620 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
17630 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
17640 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
17650 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
17660 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
17670 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
17680 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
17690 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
176a0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
176b0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
176c0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
176d0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
176e0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
176f0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
17700 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
17710 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
17720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17730 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
17740 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17750 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
17760 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
17770 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
17780 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
17790 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
177a0 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
177b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
177c0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
177d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
177e0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
177f0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53  sy handler..*/.S
17800 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
17810 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
17820 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
17830 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
17840 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
17850 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
17860 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
17870 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
17880 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
17890 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
178a0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
178b0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
178c0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
178d0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
178e0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
178f0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
17900 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
17910 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
17920 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
17930 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
17940 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
17950 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
17960 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
17970 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
17980 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
17990 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
179a0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
179b0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
179c0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
179d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
179e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
179f0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
17a00 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
17a10 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
17a20 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
17a30 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
17a40 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
17a50 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
17a60 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
17a70 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
17a80 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
17a90 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
17aa0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
17ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
17ac0 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
17ad0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
17ae0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
17af0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
17b00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
17b10 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
17b20 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
17b30 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
17b40 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
17b50 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
17b60 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  red.)^.*/.SQLITE
17b70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
17b80 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
17b90 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
17ba0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17bb0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
17bc0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
17bd0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
17be0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
17bf0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
17c00 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
17c10 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
17c20 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
17c30 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17c40 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
17c50 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
17c60 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
17c70 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
17c80 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
17c90 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
17ca0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
17cb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
17cc0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
17cd0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
17ce0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
17cf0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
17d00 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
17d10 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
17d20 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
17d30 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
17d40 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
17d50 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
17d60 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
17d70 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
17d80 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
17d90 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
17da0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
17db0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
17dc0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
17dd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
17de0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
17df0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
17e00 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
17e10 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
17e20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
17e30 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
17e40 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
17e50 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
17e60 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
17e70 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
17e80 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
17e90 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
17ea0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
17eb0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
17ec0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
17ed0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
17ee0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
17ef0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
17f00 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
17f10 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
17f20 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
17f30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
17f40 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
17f50 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
17f60 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
17f70 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
17f80 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
17f90 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
17fa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
17fb0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
17fc0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
17fd0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
17fe0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
17ff0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
18000 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
18010 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
18020 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
18030 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
18040 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
18050 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
18060 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
18070 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
18080 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
18090 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
180a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
180b0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
180c0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
180d0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
180e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
180f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
18100 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
18110 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
18120 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
18130 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
18140 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
18150 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
18160 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
18170 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
18180 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
18190 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
181a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
181b0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
181c0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
181d0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
181e0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
181f0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
18200 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
18210 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
18220 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
18230 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
18240 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
18250 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
18260 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
18270 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
18280 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
18290 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
182a0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
182b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
182c0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
182d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
182e0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
182f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
18300 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
18310 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
18320 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
18330 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
18340 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
18350 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
18360 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
18370 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
18380 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
18390 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
183a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
183b0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
183c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
183d0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
183e0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
183f0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
18400 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
18410 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
18420 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
18430 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
18440 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
18450 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
18460 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
18470 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
18480 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
18490 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
184a0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
184b0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
184c0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
184d0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
184e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
184f0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
18500 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
18510 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
18520 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
18530 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
18540 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
18550 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
18560 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
18570 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
18580 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
18590 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
185a0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
185b0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
185c0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
185d0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
185e0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
185f0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
18600 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
18610 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
18620 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
18630 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
18640 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
18650 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
18660 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
18670 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
18680 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
18690 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
186a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
186b0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
186c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
186d0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
186e0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
186f0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
18700 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
18710 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
18720 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
18730 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
18740 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
18750 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
18760 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
18770 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
18780 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
18790 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
187a0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
187b0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
187c0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
187d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
187e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
187f0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
18800 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
18810 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
18820 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
18830 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
18840 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
18850 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
18860 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
18870 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
18880 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
18890 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
188a0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
188b0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
188c0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
188d0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
188e0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
188f0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
18900 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
18910 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
18920 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
18930 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
18940 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
18950 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
18960 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
18970 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
18980 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
18990 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
189a0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
189b0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
189c0 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
189d0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
189e0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
189f0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
18a00 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
18a10 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
18a20 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
18a30 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
18a40 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
18a50 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
18a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
18a70 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
18a80 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
18a90 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
18aa0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
18ab0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
18ac0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
18ad0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
18ae0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
18af0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
18b00 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
18b10 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
18b20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
18b30 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
18b40 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
18b50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
18b60 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
18b70 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
18b80 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
18b90 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
18ba0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
18bb0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
18bc0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
18bd0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
18be0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
18bf0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
18c00 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
18c10 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
18c20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
18c30 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
18c40 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
18c50 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
18c60 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
18c70 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
18c80 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
18c90 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
18ca0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
18cb0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
18cc0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
18cd0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
18ce0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
18cf0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
18d00 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
18d10 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
18d20 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
18d30 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
18d40 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
18d50 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
18d60 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
18d70 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
18d80 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
18d90 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
18da0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
18db0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
18dc0 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
18dd0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
18de0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
18df0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
18e00 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
18e10 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
18e20 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
18e30 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
18e40 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
18e50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
18e60 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
18e70 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
18e80 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
18e90 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
18ea0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
18eb0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
18ec0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
18ed0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
18ee0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
18ef0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
18f00 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
18f10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18f20 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
18f30 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
18f40 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
18f50 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
18f60 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
18f70 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
18f80 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
18f90 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
18fa0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
18fb0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
18fc0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
18fd0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
18fe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18ff0 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
19000 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
19010 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
19020 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
19030 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
19040 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
19050 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
19060 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
19070 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
19080 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
19090 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
190a0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
190b0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
190c0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
190d0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
190e0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
190f0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
19100 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
19110 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
19120 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
19130 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
19140 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
19150 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
19160 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
19170 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
19180 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
19190 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
191a0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
191b0 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
191c0 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
191d0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
191e0 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
191f0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
19200 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
19210 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
19220 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
19230 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
19240 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
19250 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
19260 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
19270 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
19280 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
19290 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
192a0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
192b0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
192c0 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
192d0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
192e0 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
192f0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
19300 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
19310 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
19320 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
19330 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
19340 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19350 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
19360 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
19370 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
19380 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
19390 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
193a0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
193b0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
193c0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
193d0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
193e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
193f0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
19400 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
19410 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
19420 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
19430 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
19440 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
19450 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
19460 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
19470 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
19480 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
19490 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
194a0 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
194b0 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
194c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
194d0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
194e0 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
194f0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
19500 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
19510 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
19520 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
19530 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
19540 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
19550 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
19560 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
19570 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
19580 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
19590 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
195a0 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
195b0 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
195c0 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
195d0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
195e0 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
195f0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
19600 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
19610 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
19620 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
19630 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
19640 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
19650 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
19660 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
19670 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
19680 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
19690 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
196a0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
196b0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
196c0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
196d0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
196e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
196f0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
19700 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
19710 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
19720 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
19730 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
19740 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
19750 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
19760 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
19770 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
19780 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
19790 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
197a0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
197b0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
197c0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
197d0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
197e0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
197f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
19800 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
19810 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
19820 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
19830 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
19840 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
19850 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
19860 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
19870 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
19880 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
19890 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
198a0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
198b0 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
198c0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
198d0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
198e0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
198f0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
19900 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
19910 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
19920 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
19930 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
19940 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
19950 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d   char *sqlite3_m
19960 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
19970 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
19980 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
19990 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
199a0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
199b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
199c0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
199d0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
199e0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
199f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
19a00 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
19a10 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
19a20 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
19a30 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
19a40 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
19a50 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
19a60 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
19a70 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
19a80 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
19a90 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
19aa0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
19ab0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19ac0 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
19ad0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
19ae0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
19af0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
19b00 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
19b10 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
19b20 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
19b30 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
19b40 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
19b50 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
19b60 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
19b70 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
19b80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19b90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
19ba0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
19bb0 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
19bc0 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
19bd0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
19be0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
19bf0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
19c00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19c10 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
19c20 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
19c30 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
19c40 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
19c50 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
19c60 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
19c70 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
19c80 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
19c90 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
19ca0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19cb0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
19cc0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
19cd0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
19ce0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
19cf0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
19d00 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
19d10 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
19d20 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
19d30 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
19d40 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
19d50 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
19d60 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
19d70 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
19d80 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
19d90 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
19da0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
19db0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
19dc0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
19dd0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
19de0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
19df0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
19e00 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
19e10 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
19e20 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
19e30 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
19e40 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
19e50 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
19e60 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
19e70 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
19e80 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
19e90 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
19ea0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
19eb0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
19ec0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
19ed0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
19ee0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
19ef0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
19f00 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
19f10 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
19f20 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
19f30 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
19f40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
19f50 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
19f60 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
19f70 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
19f80 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
19f90 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
19fa0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
19fb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
19fc0 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
19fd0 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
19fe0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
19ff0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
1a000 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1a010 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
1a020 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
1a030 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
1a040 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1a050 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1a060 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1a070 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1a080 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1a090 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1a0a0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1a0b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
1a0c0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1a0d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1a0e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1a0f0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
1a100 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a110 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1a120 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
1a130 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1a140 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1a150 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1a160 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1a170 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
1a180 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
1a190 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1a1a0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1a1b0 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
1a1c0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1a1d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1a1e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1a1f0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1a200 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1a210 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
1a220 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1a230 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
1a240 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1a250 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1a260 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1a270 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1a280 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1a290 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1a2a0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1a2b0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1a2c0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1a2d0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1a2e0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
1a2f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1a300 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1a310 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a320 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
1a330 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
1a340 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
1a350 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1a360 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1a370 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a380 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
1a390 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1a3a0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1a3b0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1a3c0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1a3d0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1a3e0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1a3f0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1a400 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1a410 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1a420 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1a430 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1a440 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1a450 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1a460 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1a470 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1a480 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1a490 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1a4a0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1a4b0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1a4c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1a4d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1a4e0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1a4f0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1a500 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1a510 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1a520 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1a530 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1a540 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1a550 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1a560 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1a570 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1a580 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1a590 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1a5a0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1a5b0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1a5c0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1a5d0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1a5e0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1a5f0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1a600 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1a610 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1a620 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1a630 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1a640 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1a650 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1a660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1a670 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1a680 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1a690 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1a6a0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1a6b0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1a6c0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1a6d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1a6e0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1a6f0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1a700 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1a710 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1a720 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1a730 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1a740 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1a750 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1a760 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1a770 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1a780 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1a790 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1a7a0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1a7b0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1a7c0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1a7d0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1a7e0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1a7f0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1a800 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1a810 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1a820 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1a830 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1a840 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a850 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1a860 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
1a870 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1a880 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1a890 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1a8a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1a8b0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1a8c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1a8d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1a8e0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1a8f0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1a900 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
1a910 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
1a920 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
1a930 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
1a940 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
1a950 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
1a960 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
1a970 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
1a980 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
1a990 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1a9a0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
1a9b0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
1a9c0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1a9d0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
1a9e0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
1a9f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1aa00 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
1aa10 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1aa20 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
1aa30 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
1aa40 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
1aa50 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
1aa60 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
1aa70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1aa80 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
1aa90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1aaa0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
1aab0 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
1aac0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
1aad0 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
1aae0 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
1aaf0 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
1ab00 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1ab10 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1ab20 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
1ab30 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1ab40 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1ab50 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
1ab60 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
1ab70 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
1ab80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1ab90 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1aba0 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
1abb0 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
1abc0 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
1abd0 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
1abe0 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
1abf0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
1ac00 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
1ac10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1ac20 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
1ac30 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
1ac40 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1ac50 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
1ac60 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
1ac70 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
1ac80 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
1ac90 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1aca0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1acb0 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
1acc0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1acd0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1ace0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
1acf0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
1ad00 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
1ad10 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
1ad20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
1ad30 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1ad40 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1ad50 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1ad60 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
1ad70 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1ad80 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1ad90 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1ada0 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1adb0 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1adc0 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1add0 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1ade0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1adf0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1ae00 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1ae10 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1ae20 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1ae30 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1ae40 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1ae50 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1ae60 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1ae70 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1ae80 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1ae90 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1aea0 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1aeb0 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1aec0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1aed0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1aee0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1aef0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1af00 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1af10 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1af20 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1af30 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1af40 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1af50 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1af60 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1af70 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1af80 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
1af90 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
1afa0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
1afb0 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
1afc0 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
1afd0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
1afe0 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
1aff0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1b000 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
1b010 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
1b020 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1b030 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1b040 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1b050 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
1b060 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
1b070 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
1b080 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1b090 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1b0a0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1b0b0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1b0c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1b0d0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1b0e0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
1b0f0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1b100 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1b110 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1b120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b130 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1b140 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1b150 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1b160 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1b170 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1b180 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1b190 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1b1a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b1b0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1b1c0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1b1d0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1b1e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1b1f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1b200 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1b210 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1b220 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1b230 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1b240 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1b250 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b260 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1b270 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1b280 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1b290 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1b2a0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1b2b0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1b2c0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1b2d0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1b2e0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1b2f0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1b300 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1b310 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b320 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1b330 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1b340 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1b350 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1b360 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b370 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1b380 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1b390 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1b3a0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1b3b0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1b3c0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1b3d0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1b3e0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b3f0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
1b400 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
1b410 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1b420 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
1b430 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
1b440 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
1b450 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
1b460 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
1b470 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b480 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
1b490 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1b4a0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
1b4b0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
1b4c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1b4d0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
1b4e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b4f0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1b500 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1b510 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
1b520 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1b530 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1b540 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
1b550 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1b560 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1b570 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
1b580 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
1b590 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
1b5a0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
1b5b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1b5c0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
1b5d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
1b5e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1b5f0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1b600 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
1b610 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1b620 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1b630 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1b640 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
1b650 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
1b660 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
1b670 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1b680 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1b690 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1b6a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
1b6b0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
1b6c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1b6d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1b6e0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
1b6f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b700 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
1b710 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1b720 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
1b730 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
1b740 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1b750 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1b760 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1b770 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
1b780 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1b790 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
1b7a0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1b7b0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
1b7c0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1b7d0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
1b7e0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
1b7f0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
1b800 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1b810 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b820 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1b830 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
1b840 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1b850 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1b860 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1b870 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1b880 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
1b890 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
1b8a0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
1b8b0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
1b8c0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
1b8d0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1b8e0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
1b8f0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
1b900 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
1b910 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
1b920 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
1b930 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
1b940 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
1b950 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
1b960 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
1b970 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
1b980 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
1b990 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1b9a0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1b9b0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
1b9c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b9d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
1b9e0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
1b9f0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
1ba00 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
1ba10 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
1ba20 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
1ba30 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
1ba40 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
1ba50 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
1ba60 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
1ba70 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
1ba80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ba90 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
1baa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1bab0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
1bac0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
1bad0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
1bae0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
1baf0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
1bb00 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
1bb10 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
1bb20 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
1bb30 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
1bb40 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
1bb50 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
1bb60 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
1bb70 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
1bb80 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
1bb90 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
1bba0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
1bbb0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
1bbc0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
1bbd0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
1bbe0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
1bbf0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1bc00 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
1bc10 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
1bc20 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
1bc30 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
1bc40 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
1bc50 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
1bc60 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
1bc70 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
1bc80 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
1bc90 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
1bca0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
1bcb0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
1bcc0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
1bcd0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
1bce0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
1bcf0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1bd00 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
1bd10 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
1bd20 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
1bd30 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
1bd40 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
1bd50 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
1bd60 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
1bd70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
1bd80 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
1bd90 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
1bda0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
1bdb0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1bdc0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
1bdd0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
1bde0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
1bdf0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
1be00 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
1be10 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
1be20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
1be30 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
1be40 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
1be50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
1be60 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
1be70 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
1be80 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
1be90 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
1bea0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
1beb0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
1bec0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
1bed0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
1bee0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
1bef0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
1bf00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
1bf10 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1bf20 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1bf30 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1bf40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1bf50 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1bf60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1bf70 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
1bf80 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1bf90 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1bfa0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1bfb0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1bfc0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1bfd0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1bfe0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1bff0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1c000 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
1c010 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1c020 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
1c030 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
1c040 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
1c050 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
1c060 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
1c070 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
1c080 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
1c090 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
1c0a0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
1c0b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
1c0c0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
1c0d0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
1c0e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c0f0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
1c100 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
1c110 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1c120 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
1c130 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c140 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1c150 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
1c160 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1c170 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1c180 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
1c190 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
1c1a0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
1c1b0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
1c1c0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
1c1d0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
1c1e0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
1c1f0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1c200 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
1c210 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
1c220 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
1c230 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
1c240 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1c250 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
1c260 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c  a change..*/.SQL
1c270 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1c280 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1c290 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1c2a0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1c2b0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1c2c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1c2d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1c2e0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1c2f0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1c300 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c310 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1c320 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
1c330 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1c340 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1c350 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c360 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1c370 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1c380 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1c390 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1c3a0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1c3b0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1c3c0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1c3d0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1c3e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1c3f0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1c400 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1c410 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1c420 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1c430 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1c440 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1c450 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
1c460 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
1c470 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
1c480 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20  SQLITE_ROLLBACK 
1c490 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a  | return code].*
1c4a0 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  * from the [sqli
1c4b0 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1c4c0 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1c4d0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1c4e0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1c4f0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1c500 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1c510 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1c520 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1c530 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1c540 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1c550 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1c560 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1c570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1c580 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1c590 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1c5a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1c5b0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1c5c0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1c5d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c5e0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1c5f0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1c600 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1c610 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1c620 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1c630 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c640 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1c650 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1c660 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1c670 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1c680 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1c690 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1c6a0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1c6b0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1c6c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c6d0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1c6e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1c6f0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1c700 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1c710 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1c720 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1c730 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1c740 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1c750 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1c760 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1c770 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1c780 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1c790 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1c7a0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1c7b0 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1c7c0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1c7d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1c7e0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1c7f0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1c800 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1c810 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1c820 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1c830 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1c840 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1c850 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1c860 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1c870 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c880 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1c890 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1c8a0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1c8b0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1c8c0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1c8d0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1c8e0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1c8f0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1c900 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1c910 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1c920 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1c930 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1c940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c950 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1c960 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1c970 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1c980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c990 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1c9a0 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1c9b0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1c9c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1c9d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1c9e0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1c9f0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1ca00 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1ca10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ca20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ca30 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1ca40 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1ca50 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1ca60 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ca70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ca80 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1ca90 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1caa0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1cab0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1cac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1cad0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1cae0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1caf0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1cb00 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1cb10 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1cb20 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1cb30 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1cb40 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1cb50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1cb60 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1cb70 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1cb80 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1cb90 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1cba0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1cbb0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1cbc0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1cbd0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1cbe0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1cbf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1cc00 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1cc10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1cc20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1cc30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1cc40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1cc50 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1cc60 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1cc70 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1cc80 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1cc90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1cca0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1ccb0 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1ccc0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1ccd0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1cce0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ccf0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1cd00 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1cd10 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1cd20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1cd30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cd40 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1cd50 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1cd60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1cd70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1cd80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1cd90 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1cda0 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1cdb0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1cdc0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1cdd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1cde0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1cdf0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1ce00 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1ce10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ce20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ce30 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1ce40 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1ce50 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1ce60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1ce70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ce80 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1ce90 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1cea0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1ceb0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1cec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1ced0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1cee0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1cef0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1cf00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1cf10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1cf20 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1cf30 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
1cf40 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
1cf50 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
1cf60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1cf70 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1cf80 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
1cf90 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1cfa0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1cfb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
1cfc0 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
1cfd0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
1cfe0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1cff0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1d000 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1d010 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
1d020 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
1d030 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
1d040 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d050 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
1d060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1d070 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1d080 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1d090 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1d0a0 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
1d0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
1d0c0 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
1d0d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1d0e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d0f0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
1d100 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
1d110 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1d120 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
1d130 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d140 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
1d150 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
1d160 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1d170 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
1d180 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d190 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
1d1a0 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
1d1b0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1d1c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1d1d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d1e0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
1d1f0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
1d200 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1d210 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d220 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d230 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
1d240 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
1d250 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d260 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1d270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d280 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
1d290 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
1d2a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d2b0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1d2c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d2d0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
1d2e0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
1d2f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
1d300 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
1d310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d320 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
1d330 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
1d340 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
1d350 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
1d360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d370 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1d380 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1d390 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1d3a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d3b0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1d3c0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1d3d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1d3e0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1d3f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1d400 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1d410 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1d420 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1d430 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1d440 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1d450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1d460 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1d470 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1d480 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1d490 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1d4a0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1d4b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1d4c0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1d4d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d4e0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1d4f0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1d500 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1d510 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1d520 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1d530 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1d540 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1d550 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1d560 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1d570 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1d580 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1d590 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1d5a0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1d5b0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1d5c0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1d5d0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1d5e0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1d5f0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1d600 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1d610 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1d620 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
1d630 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1d640 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1d650 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1d660 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1d670 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1d680 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1d690 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1d6a0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
1d6b0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
1d6c0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
1d6d0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
1d6e0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
1d6f0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
1d700 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
1d710 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
1d720 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1d730 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
1d740 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
1d750 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
1d760 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
1d770 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1d780 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
1d790 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
1d7a0 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
1d7b0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
1d7c0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
1d7d0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
1d7e0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
1d7f0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1d800 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
1d810 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
1d820 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
1d830 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
1d840 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
1d850 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1d860 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
1d870 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
1d880 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
1d890 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1d8a0 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
1d8b0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
1d8c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1d8d0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
1d8e0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1d8f0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
1d900 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
1d910 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
1d920 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1d930 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1d940 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1d950 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1d960 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1d970 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1d980 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1d990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d9a0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1d9b0 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
1d9c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
1d9d0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1d9e0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
1d9f0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
1da00 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1da10 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
1da20 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
1da30 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
1da40 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
1da50 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1da60 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1da70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1da80 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
1da90 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1daa0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
1dab0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1dac0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1dad0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1dae0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1daf0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1db00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
1db10 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
1db20 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
1db30 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
1db40 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
1db50 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
1db60 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
1db70 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1db80 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
1db90 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
1dba0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
1dbb0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
1dbc0 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
1dbd0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
1dbe0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a   callback X..**.
1dbf0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
1dc00 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1dc10 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
1dc20 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
1dc30 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1dc40 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
1dc50 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
1dc60 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
1dc70 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
1dc80 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
1dc90 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
1dca0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
1dcb0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1dcc0 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
1dcd0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
1dce0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
1dcf0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
1dd00 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
1dd10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1dd20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1dd30 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1dd40 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
1dd50 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
1dd60 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
1dd70 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
1dd80 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
1dd90 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
1dda0 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
1ddb0 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
1ddc0 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
1ddd0 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
1dde0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1ddf0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1de00 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1de10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1de20 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1de30 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1de40 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
1de50 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1de60 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1de70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1de80 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1de90 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1dea0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1deb0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1dec0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1ded0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53  ragraph..**.*/.S
1dee0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1def0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1df00 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1df10 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1df20 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1df30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1df40 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1df50 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1df60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1df70 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1df80 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1df90 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
1dfa0 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
1dfb0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
1dfc0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1dfd0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1dfe0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
1dff0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1e000 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1e010 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
1e020 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1e030 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
1e040 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
1e050 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
1e060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e070 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
1e080 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
1e090 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
1e0a0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
1e0b0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
1e0c0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
1e0d0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
1e0e0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1e0f0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
1e100 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
1e110 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
1e120 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
1e130 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
1e140 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
1e150 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1e160 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
1e170 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
1e180 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
1e190 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
1e1a0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
1e1b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
1e1c0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
1e1d0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1e1e0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1e1f0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
1e200 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1e210 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
1e220 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
1e230 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
1e240 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
1e250 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
1e260 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
1e270 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
1e280 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
1e290 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
1e2a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
1e2b0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
1e2c0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
1e2d0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
1e2e0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
1e2f0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
1e300 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1e310 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
1e320 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
1e330 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1e340 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
1e350 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1e360 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1e370 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
1e380 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
1e390 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
1e3a0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
1e3b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1e3c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1e3d0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1e3e0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
1e3f0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
1e400 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
1e410 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
1e420 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
1e430 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
1e440 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
1e450 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
1e460 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1e470 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
1e480 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
1e490 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
1e4a0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
1e4b0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
1e4c0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
1e4d0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1e4e0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
1e4f0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
1e500 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1e510 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
1e520 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
1e530 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
1e540 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
1e550 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
1e560 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1e570 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
1e580 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1e590 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1e5a0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1e5b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
1e5c0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
1e5d0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
1e5e0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
1e5f0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
1e600 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1e610 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1e620 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1e630 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1e640 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1e650 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1e660 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1e670 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1e680 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1e690 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1e6a0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1e6b0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1e6c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e6d0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1e6e0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1e6f0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
1e700 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
1e710 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
1e720 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
1e730 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1e740 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1e750 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
1e760 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
1e770 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
1e780 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
1e790 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
1e7a0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1e7b0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1e7c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1e7d0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1e7e0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1e7f0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1e800 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1e810 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1e820 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
1e830 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
1e840 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
1e850 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
1e860 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
1e870 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
1e880 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1e890 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1e8a0 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
1e8b0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
1e8c0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
1e8d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1e8e0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
1e8f0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
1e900 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1e910 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
1e920 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1e930 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
1e940 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1e950 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
1e960 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
1e970 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
1e980 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
1e990 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
1e9a0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1e9b0 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
1e9c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1e9d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
1e9e0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
1e9f0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
1ea00 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
1ea10 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
1ea20 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
1ea30 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
1ea40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1ea50 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
1ea60 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
1ea70 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
1ea80 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
1ea90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1eaa0 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
1eab0 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
1eac0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
1ead0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
1eae0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
1eaf0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
1eb00 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
1eb10 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1eb20 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
1eb30 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1eb40 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1eb50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1eb60 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
1eb70 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
1eb80 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
1eb90 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
1eba0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1ebb0 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
1ebc0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
1ebd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
1ebe0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1ebf0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
1ec00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1ec10 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
1ec20 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1ec30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1ec40 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
1ec50 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
1ec60 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
1ec70 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
1ec80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1ec90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1eca0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ecb0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1ecc0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1ecd0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1ece0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1ecf0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1ed00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1ed10 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1ed20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1ed30 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1ed40 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1ed50 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1ed60 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1ed70 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1ed80 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1ed90 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
1eda0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1edb0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1edc0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1edd0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
1ede0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
1edf0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1ee00 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
1ee10 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1ee20 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1ee30 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1ee40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ee50 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1ee60 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1ee70 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1ee80 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1ee90 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1eea0 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1eeb0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1eec0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1eed0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1eee0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1eef0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1ef00 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1ef10 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1ef20 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1ef30 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1ef40 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1ef50 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1ef60 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1ef70 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1ef80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1ef90 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1efa0 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1efb0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1efc0 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1efd0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1efe0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
1eff0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
1f000 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
1f010 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
1f020 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
1f030 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1f040 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1f050 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
1f060 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
1f070 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
1f080 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
1f090 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
1f0a0 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
1f0b0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
1f0c0 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
1f0d0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
1f0e0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
1f0f0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
1f100 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
1f110 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
1f120 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
1f130 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
1f140 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
1f150 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1f160 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
1f170 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
1f180 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
1f190 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f1a0 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
1f1b0 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
1f1c0 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
1f1d0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
1f1e0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
1f1f0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
1f200 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
1f210 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
1f220 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
1f230 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
1f240 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
1f250 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1f260 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
1f270 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1f280 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
1f290 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
1f2a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
1f2b0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
1f2c0 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
1f2d0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
1f2e0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
1f2f0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
1f300 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
1f310 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1f320 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
1f330 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
1f340 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
1f350 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
1f360 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
1f370 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
1f380 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
1f390 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
1f3a0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
1f3b0 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
1f3c0 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
1f3d0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
1f3e0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
1f3f0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
1f400 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
1f410 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
1f420 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
1f430 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
1f440 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
1f450 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
1f460 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1f470 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
1f480 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
1f490 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
1f4a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
1f4b0 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
1f4c0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
1f4d0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
1f4e0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
1f4f0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
1f500 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
1f510 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
1f520 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
1f530 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
1f540 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
1f550 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
1f560 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
1f570 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
1f580 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
1f590 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
1f5a0 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
1f5b0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
1f5c0 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
1f5d0 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68   ^On windows, th
1f5e0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
1f5f0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
1f600 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
1f610 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
1f620 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a  on (e.g. "C:")..
1f630 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
1f640 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1f650 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
1f660 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1f670 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
1f680 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
1f690 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
1f6a0 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
1f6b0 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
1f6c0 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
1f6d0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
1f6e0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
1f6f0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
1f700 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
1f710 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
1f720 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
1f730 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
1f740 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
1f750 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
1f760 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
1f770 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
1f780 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
1f790 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
1f7a0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1f7b0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1f7c0 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
1f7d0 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
1f7e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
1f7f0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
1f800 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
1f810 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
1f820 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
1f830 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
1f840 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
1f850 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
1f860 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
1f870 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
1f880 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f890 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
1f8a0 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
1f8b0 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
1f8c0 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
1f8d0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
1f8e0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
1f8f0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
1f900 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
1f910 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
1f920 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1f930 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1f940 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
1f950 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
1f960 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
1f970 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
1f980 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
1f990 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
1f9a0 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
1f9b0 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
1f9c0 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
1f9d0 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
1f9e0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
1f9f0 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
1fa00 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
1fa10 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1fa20 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
1fa30 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
1fa40 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
1fa50 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
1fa60 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
1fa70 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
1fa80 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
1fa90 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1faa0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1fab0 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
1fac0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
1fad0 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
1fae0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1faf0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1fb00 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
1fb10 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
1fb20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
1fb30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1fb40 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
1fb50 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1fb60 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
1fb70 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
1fb80 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
1fb90 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
1fba0 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
1fbb0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1fbc0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
1fbd0 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
1fbe0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
1fbf0 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
1fc00 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
1fc10 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
1fc20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
1fc30 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
1fc40 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
1fc50 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
1fc60 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
1fc70 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
1fc80 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
1fc90 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
1fca0 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
1fcb0 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
1fcc0 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
1fcd0 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
1fce0 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
1fcf0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
1fd00 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1fd10 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
1fd20 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
1fd30 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
1fd40 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
1fd50 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
1fd60 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
1fd70 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
1fd80 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
1fd90 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
1fda0 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
1fdb0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
1fdc0 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
1fdd0 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
1fde0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
1fdf0 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
1fe00 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
1fe10 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
1fe20 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
1fe30 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
1fe40 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
1fe50 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
1fe60 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1fe70 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
1fe80 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
1fe90 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
1fea0 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
1feb0 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
1fec0 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
1fed0 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
1fee0 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
1fef0 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65 71  ny behaviour req
1ff00 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
1ff10 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
1ff20 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1ff30 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
1ff40 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
1ff50 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  g..** </ul>.**.*
1ff60 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
1ff70 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
1ff80 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
1ff90 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
1ffa0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
1ffb0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
1ffc0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1ffd0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
1ffe0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
1fff0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
20000 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
20010 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
20020 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
20030 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
20040 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
20050 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
20060 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
20070 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
20080 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
20090 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
200a0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
200b0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
200c0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
200d0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
200e0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
200f0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
20100 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
20110 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
20120 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
20130 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
20140 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
20150 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
20160 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
20170 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
20180 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
20190 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
201a0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
201b0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
201c0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
201d0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
201e0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
201f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20200 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
20210 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
20220 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
20230 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
20240 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
20250 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
20260 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
20270 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
20280 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
20290 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
202a0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
202b0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
202c0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
202d0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
202e0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
202f0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
20300 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
20310 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
20320 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
20330 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
20340 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
20350 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
20360 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
20370 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
20380 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
20390 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
203a0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
203b0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
203c0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
203d0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
203e0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
203f0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
20400 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
20410 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
20420 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
20430 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
20440 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
20450 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
20460 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
20470 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
20480 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
20490 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
204a0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
204b0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
204c0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
204d0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
204e0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
204f0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
20500 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
20510 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64  =unix-nolock <td
20520 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
20530 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
20540 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
20550 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
20560 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e  S "unix-nolock".
20570 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
20580 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
20590 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
205a0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
205b0 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
205c0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
205d0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
205e0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
205f0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
20600 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
20610 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
20620 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
20630 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
20640 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
20650 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
20660 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
20670 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
20680 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
20690 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
206a0 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
206b0 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
206c0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
206d0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
206e0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
206f0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
20700 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
20710 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
20720 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
20730 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
20740 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
20750 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
20760 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
20770 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
20780 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
20790 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
207a0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
207b0 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
207c0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
207d0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
207e0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
207f0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
20800 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
20810 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
20820 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
20830 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
20840 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
20850 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
20860 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
20870 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
20880 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
20890 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
208a0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
208b0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
208c0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
208d0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
208e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
208f0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
20900 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
20910 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
20920 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
20930 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
20940 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
20950 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
20960 76 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  v2()..*/.SQLITE_
20970 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
20980 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
20990 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
209a0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
209b0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
209c0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
209d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
209e0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
209f0 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
20a00 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
20a10 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
20a20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
20a30 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
20a40 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
20a50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
20a60 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
20a70 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
20a80 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
20a90 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
20aa0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
20ab0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
20ac0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
20ad0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
20ae0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
20af0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
20b00 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
20b10 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
20b20 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
20b30 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
20b40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
20b50 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
20b60 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
20b70 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
20b80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20b90 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
20ba0 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
20bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
20bc0 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
20bd0 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
20be0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
20bf0 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
20c00 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
20c10 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
20c20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
20c30 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
20c40 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
20c50 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
20c60 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
20c70 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
20c80 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
20c90 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
20ca0 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
20cb0 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
20cc0 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
20cd0 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
20ce0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
20cf0 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
20d00 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
20d10 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
20d20 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
20d30 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
20d40 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
20d50 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
20d60 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
20d70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
20d80 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
20d90 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
20da0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
20db0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
20dc0 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
20dd0 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
20de0 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
20df0 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
20e00 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
20e10 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
20e20 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
20e30 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
20e40 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
20e50 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
20e60 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
20e70 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
20e80 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
20e90 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
20ea0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
20eb0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20ec0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
20ed0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
20ee0 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
20ef0 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
20f00 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
20f10 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
20f20 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
20f30 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
20f40 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
20f50 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
20f60 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
20f70 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
20f80 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
20f90 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
20fa0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
20fb0 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
20fc0 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
20fd0 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
20fe0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
20ff0 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
21000 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
21010 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
21020 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
21030 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
21040 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
21050 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
21060 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
21070 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
21080 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
21090 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
210a0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
210b0 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
210c0 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
210d0 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
210e0 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
210f0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
21100 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
21110 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
21120 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
21130 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
21140 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
21150 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
21160 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
21170 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
21180 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
21190 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
211a0 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
211b0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
211c0 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
211d0 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
211e0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
211f0 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
21200 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
21210 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
21220 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
21230 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
21240 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
21250 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
21260 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
21270 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
21280 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
21290 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
212a0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
212b0 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
212c0 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
212d0 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
212e0 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
212f0 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
21300 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
21310 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
21320 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
21330 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
21340 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
21350 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
21360 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
21370 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
21380 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ble..*/.SQLITE_A
21390 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
213a0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
213b0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
213c0 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
213d0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
213e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
213f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
21400 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
21410 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
21420 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
21430 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45  Default);.SQLITE
21440 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
21450 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
21460 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
21470 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
21480 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
21490 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
214a0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
214b0 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
214c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
214d0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
214e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
214f0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
21500 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
21510 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
21520 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
21530 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
21540 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
21550 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
21560 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
21570 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
21580 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
21590 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
215a0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
215b0 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
215c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
215d0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
215e0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
215f0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
21600 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
21610 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
21620 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
21630 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
21640 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
21650 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
21660 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
21670 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
21680 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
21690 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
216a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
216b0 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
216c0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
216d0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
216e0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
216f0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
21700 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
21710 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
21720 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
21730 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
21740 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
21750 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
21760 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
21770 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
21780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
21790 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
217a0 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
217b0 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
217c0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
217d0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
217e0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
217f0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
21800 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
21810 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
21820 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
21830 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
21840 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
21850 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
21860 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
21870 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
21880 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
21890 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
218a0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
218b0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
218c0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
218d0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
218e0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
218f0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
21900 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
21910 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
21920 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
21930 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
21940 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
21950 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
21960 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
21970 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
21980 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
21990 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
219a0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
219b0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
219c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
219d0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
219e0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
219f0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
21a00 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
21a10 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
21a20 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
21a30 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
21a40 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
21a50 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
21a60 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
21a70 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
21a80 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
21a90 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
21aa0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
21ab0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
21ac0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
21ad0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
21ae0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
21af0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
21b00 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
21b10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
21b20 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
21b30 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
21b40 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
21b50 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
21b60 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
21b70 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
21b80 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
21b90 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  db);.SQLITE_API 
21ba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
21bb0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
21bc0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
21bd0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
21be0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
21bf0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
21c00 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
21c10 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
21c20 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
21c30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21c40 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
21c50 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
21c60 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
21c70 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
21c80 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
21c90 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
21ca0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
21cb0 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
21cc0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
21cd0 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
21ce0 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
21cf0 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
21d00 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
21d10 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
21d20 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
21d30 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
21d40 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
21d50 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
21d60 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
21d70 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
21d80 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
21d90 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
21da0 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
21db0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
21dc0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
21dd0 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
21de0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
21df0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
21e00 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
21e10 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
21e20 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
21e30 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
21e40 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
21e50 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
21e60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21e70 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
21e80 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
21e90 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
21ea0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21eb0 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
21ec0 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
21ed0 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
21ee0 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
21ef0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
21f00 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
21f10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21f20 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
21f30 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
21f40 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
21f50 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
21f60 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
21f70 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
21f80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
21f90 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
21fa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
21fb0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
21fc0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
21fd0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
21fe0 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
21ff0 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
22000 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
22010 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
22020 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
22030 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
22040 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
22050 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
22060 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
22070 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22080 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
22090 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
220a0 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
220b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
220c0 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
220d0 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
220e0 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
220f0 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
22100 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
22110 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
22120 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
22130 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
22140 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
22150 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
22160 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
22170 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
22180 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
22190 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
221a0 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
221b0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
221c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
221d0 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
221e0 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
221f0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
22200 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
22210 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
22220 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
22230 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
22240 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
22250 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
22260 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
22270 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
22280 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
22290 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
222a0 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
222b0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
222c0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
222d0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
222e0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
222f0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
22300 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
22310 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
22320 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
22330 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
22340 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
22350 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
22360 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
22370 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
22380 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
22390 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
223a0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
223b0 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
223c0 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
223d0 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
223e0 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
223f0 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
22400 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
22410 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
22420 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
22430 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
22440 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
22450 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
22460 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
22470 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
22480 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
22490 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
224a0 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
224b0 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
224c0 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
224d0 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
224e0 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
224f0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
22500 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
22510 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
22520 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
22530 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
22540 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
22550 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
22560 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
22570 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
22580 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
22590 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
225a0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
225b0 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
225c0 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
225d0 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
225e0 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
225f0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
22600 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
22610 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
22620 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
22630 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
22640 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
22650 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
22660 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
22670 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
22680 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
22690 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
226a0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
226b0 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
226c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
226d0 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
226e0 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
226f0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
22700 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
22710 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
22720 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
22730 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
22740 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
22750 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
22760 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
22770 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
22780 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22790 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
227a0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
227b0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
227c0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
227d0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
227e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
227f0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
22800 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
22810 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
22820 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
22830 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
22840 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
22850 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
22860 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
22870 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
22880 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
22890 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
228a0 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
228b0 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
228c0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
228d0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
228e0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
228f0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
22900 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
22910 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
22920 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22930 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
22940 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
22950 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
22960 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
22970 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
22980 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
22990 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
229a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
229b0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
229c0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
229d0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
229e0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
229f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
22a00 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
22a10 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
22a20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
22a30 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
22a40 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
22a50 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
22a60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22a70 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
22a80 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
22a90 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
22aa0 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
22ab0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
22ac0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
22ad0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
22ae0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
22af0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
22b00 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
22b10 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
22b20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
22b30 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
22b40 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
22b50 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
22b60 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
22b70 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
22b80 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
22b90 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
22ba0 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
22bb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22bc0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
22bd0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
22be0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
22bf0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
22c00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22c10 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
22c20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
22c30 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
22c40 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
22c50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
22c60 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
22c70 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
22c80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22c90 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
22ca0 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
22cb0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
22cc0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
22cd0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
22ce0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
22cf0 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
22d00 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
22d10 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
22d20 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
22d30 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
22d40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
22d50 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
22d60 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
22d70 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
22d80 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
22d90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
22da0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
22db0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
22dc0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
22dd0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
22de0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
22df0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22e00 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
22e10 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
22e20 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
22e30 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
22e40 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
22e50 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
22e60 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
22e70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
22e80 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
22e90 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
22ea0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22eb0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
22ec0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
22ed0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
22ee0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
22ef0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
22f00 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
22f10 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
22f20 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22f30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
22f40 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
22f50 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
22f60 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
22f70 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
22f80 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
22f90 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
22fa0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
22fb0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
22fc0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
22fd0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
22fe0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
22ff0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
23000 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
23010 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
23020 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
23030 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
23040 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
23050 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
23060 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
23070 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
23080 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
23090 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
230a0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
230b0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
230c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
230d0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
230e0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
230f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
23100 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
23110 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
23120 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
23130 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
23140 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
23150 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
23160 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
23170 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
23180 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23190 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
231a0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
231b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
231c0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
231d0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
231e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
231f0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
23200 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
23210 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23220 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
23230 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
23240 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23250 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
23260 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
23270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23280 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
23290 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
232a0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
232b0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
232c0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
232d0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
232e0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
232f0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
23300 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
23310 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
23320 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
23330 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
23340 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
23350 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
23360 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23370 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
23380 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
23390 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
233a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
233b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
233c0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
233d0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
233e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
233f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
23400 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
23410 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
23420 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
23430 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
23440 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
23450 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
23460 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
23470 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
23480 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
23490 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
234a0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
234b0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
234c0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
234d0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
234e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
234f0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
23500 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
23510 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
23520 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
23530 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
23540 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
23550 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
23560 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
23570 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
23580 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
23590 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
235a0 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
235b0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
235c0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
235d0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
235e0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
235f0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
23600 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
23610 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
23620 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
23630 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
23640 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
23650 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
23660 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
23670 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
23680 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
23690 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
236a0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
236b0 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
236c0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
236d0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
236e0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
236f0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
23700 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
23710 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
23720 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
23730 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
23740 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
23750 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
23760 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
23770 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
23780 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
23790 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
237a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
237b0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
237c0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
237d0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
237e0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
237f0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
23800 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
23810 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
23820 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
23830 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
23840 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
23850 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
23860 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
23870 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
23880 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
23890 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
238a0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
238b0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
238c0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
238d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
238e0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
238f0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
23900 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23910 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
23920 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
23930 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
23940 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
23950 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
23960 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
23970 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
23980 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
23990 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
239a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
239b0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
239c0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
239d0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
239e0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
239f0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
23a00 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
23a10 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23a20 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
23a30 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
23a40 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
23a50 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
23a60 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
23a70 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
23a80 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
23a90 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
23aa0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
23ab0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
23ac0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
23ad0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
23ae0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
23af0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
23b00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
23b10 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
23b20 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
23b30 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
23b40 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
23b50 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
23b60 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
23b70 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
23b80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
23b90 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
23ba0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
23bb0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
23bc0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
23bd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
23be0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
23bf0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
23c00 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
23c10 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
23c20 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
23c30 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
23c40 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
23c50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
23c60 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
23c70 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
23c80 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
23c90 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
23ca0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
23cb0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
23cc0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
23cd0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
23ce0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
23cf0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
23d00 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
23d10 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
23d20 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
23d30 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
23d40 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
23d50 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
23d60 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
23d70 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
23d80 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
23d90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23da0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
23db0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
23dc0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
23dd0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
23de0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
23df0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
23e00 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
23e10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23e20 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
23e30 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
23e40 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
23e50 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
23e60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
23e70 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
23e80 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
23e90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
23ea0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
23eb0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
23ec0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
23ed0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
23ee0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
23ef0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
23f00 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
23f10 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
23f20 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
23f30 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
23f40 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
23f50 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
23f60 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
23f70 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
23f80 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
23f90 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
23fa0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
23fb0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
23fc0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
23fd0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
23fe0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
23ff0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
24000 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
24010 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
24020 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
24030 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
24040 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
24050 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
24060 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
24070 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
24080 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
24090 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
240a0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
240b0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
240c0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
240d0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
240e0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
240f0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
24100 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
24110 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
24120 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
24130 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
24140 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
24150 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
24160 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
24170 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
24180 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
24190 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
241a0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
241b0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
241c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
241d0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
241e0 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
241f0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ol>.*/.SQLI
24200 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24210 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
24220 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
24230 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
24240 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
24250 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
24260 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
24270 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
24280 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
24290 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
242a0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
242b0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
242c0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
242d0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
242e0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
242f0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
24300 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
24310 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
24320 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
24330 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
24340 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
24350 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
24360 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
24370 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
24380 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
24390 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
243a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
243b0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
243c0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
243d0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
243e0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
243f0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
24400 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
24410 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
24420 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
24430 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
24440 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
24450 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
24460 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
24470 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
24480 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
24490 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
244a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
244b0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
244c0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
244d0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
244e0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
244f0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
24500 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
24510 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
24520 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
24530 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
24540 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
24550 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
24560 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
24570 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
24580 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
24590 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
245a0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
245b0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
245c0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
245d0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
245e0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
245f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24600 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
24610 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
24620 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
24630 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
24640 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
24650 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
24660 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
24670 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
24680 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
24690 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
246a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
246b0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
246c0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
246d0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
246e0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
246f0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
24700 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
24710 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
24720 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
24730 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
24740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24750 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
24760 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
24770 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
24780 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
24790 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
247a0 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
247b0 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
247c0 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
247d0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
247e0 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
247f0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
24800 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
24810 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
24820 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
24830 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24840 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  16_v2()]..*/.SQL
24850 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
24860 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
24870 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
24880 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
24890 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
248a0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
248b0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
248c0 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
248d0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
248e0 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
248f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24900 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
24910 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
24920 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24930 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
24940 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
24950 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
24960 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
24970 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
24980 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
24990 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
249a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
249b0 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
249c0 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
249d0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
249e0 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
249f0 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
24a00 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
24a10 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
24a20 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
24a30 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
24a40 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
24a50 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
24a60 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
24a70 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
24a80 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
24a90 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
24aa0 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
24ab0 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
24ac0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
24ad0 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
24ae0 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
24af0 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
24b00 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
24b10 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
24b20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
24b30 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
24b40 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
24b50 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
24b60 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
24b70 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
24b80 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
24b90 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
24ba0 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
24bb0 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
24bc0 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
24bd0 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
24be0 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
24bf0 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
24c00 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
24c10 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
24c20 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
24c30 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
24c40 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
24c50 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
24c60 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
24c70 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
24c80 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
24c90 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
24ca0 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
24cb0 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
24cc0 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
24cd0 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
24ce0 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
24cf0 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
24d00 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
24d10 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
24d20 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
24d30 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
24d40 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
24d50 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
24d60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
24d70 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
24d80 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
24d90 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
24da0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
24db0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
24dc0 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
24dd0 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  sk..*/.SQLITE_AP
24de0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
24df0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
24e00 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
24e10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24e20 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
24e30 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
24e40 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
24e50 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
24e60 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
24e70 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
24e80 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
24e90 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
24ea0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24eb0 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
24ec0 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
24ed0 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
24ee0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
24ef0 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
24f00 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
24f10 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
24f20 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
24f30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
24f40 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
24f50 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
24f60 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
24f70 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
24f80 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
24f90 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
24fa0 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
24fb0 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
24fc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
24fd0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
24fe0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
24ff0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
25000 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
25010 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
25020 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
25030 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
25040 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
25050 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
25060 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
25070 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
25080 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
25090 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
250a0 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
250b0 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
250c0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
250d0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
250e0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
250f0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
25100 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
25110 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
25120 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
25130 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
25140 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
25150 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
25160 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  ion open..*/.SQL
25170 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
25180 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
25190 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
251a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
251b0 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
251c0 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
251d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
251e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
251f0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
25200 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
25210 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
25220 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
25230 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
25240 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
25250 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
25260 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
25270 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
25280 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
25290 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
252a0 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
252b0 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
252c0 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
252d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
252e0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
252f0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
25300 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
25310 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
25320 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
25330 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25340 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
25350 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
25360 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
25370 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
25380 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
25390 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
253a0 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
253b0 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
253c0 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
253d0 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
253e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
253f0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
25400 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
25410 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
25420 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
25430 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
25440 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
25450 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
25460 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25470 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
25480 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
25490 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
254a0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
254b0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
254c0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
254d0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
254e0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
254f0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
25500 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25510 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
25520 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
25530 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
25540 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25550 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
25560 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
25570 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
25580 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
25590 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
255a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
255b0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
255c0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
255d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
255e0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
255f0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
25600 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
25610 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
25620 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
25630 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
25640 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
25650 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
25660 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
25670 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
25680 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
25690 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
256a0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
256b0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
256c0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
256d0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
256e0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
256f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
25700 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
25710 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
25720 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
25730 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
25740 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
25750 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
25760 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
25770 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
25780 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
25790 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
257a0 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
257b0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
257c0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
257d0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
257e0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
257f0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
25800 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
25810 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
25820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25830 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
25840 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
25850 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
25860 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
25870 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
25880 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25890 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
258a0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
258b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
258c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
258d0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
258e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
258f0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
25900 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
25910 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
25920 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
25930 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
25940 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25950 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
25960 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
25970 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
25980 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
25990 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
259a0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
259b0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
259c0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
259d0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
259e0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
259f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
25a00 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
25a10 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
25a20 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
25a30 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
25a40 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
25a50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
25a60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
25a70 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
25a80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
25a90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
25aa0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
25ab0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
25ac0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
25ad0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
25ae0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
25af0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
25b00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
25b10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
25b20 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
25b30 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
25b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
25b50 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
25b60 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
25b70 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
25b80 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
25b90 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
25ba0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
25bb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
25bc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
25bd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
25be0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
25bf0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25c00 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
25c10 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
25c20 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
25c30 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
25c40 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
25c50 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
25c60 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
25c70 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
25c80 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
25c90 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
25ca0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
25cb0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
25cc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
25cd0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
25ce0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
25cf0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
25d00 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
25d10 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
25d20 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
25d30 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
25d40 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
25d50 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
25d60 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
25d70 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
25d80 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
25d90 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
25da0 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
25db0 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
25dc0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
25dd0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
25de0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
25df0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
25e00 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
25e10 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
25e20 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
25e30 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
25e40 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
25e50 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
25e60 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
25e70 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
25e80 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
25e90 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
25ea0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
25eb0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
25ec0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
25ed0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
25ee0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
25ef0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
25f00 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
25f10 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
25f20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
25f30 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
25f40 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
25f50 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
25f60 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
25f70 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
25f80 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
25f90 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
25fa0 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
25fb0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
25fc0 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
25fd0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
25fe0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
25ff0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
26000 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
26010 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
26020 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
26030 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
26040 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
26050 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
26060 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
26070 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
26080 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
26090 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
260a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
260b0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
260c0 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
260d0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
260e0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
260f0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
26100 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
26110 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
26120 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
26130 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
26140 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
26150 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
26160 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
26170 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
26180 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
26190 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
261a0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
261b0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
261c0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  r..**.** ^(In th
261d0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
261e0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
261f0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
26200 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
26210 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
26220 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
26230 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
26240 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
26250 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
26260 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
26270 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
26280 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
26290 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
262a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
262b0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
262c0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
262d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
262e0 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
262f0 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
26300 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
26310 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
26320 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
26330 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
26340 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
26350 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
26360 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
26370 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
26380 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
26390 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
263a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
263b0 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
263c0 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
263d0 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
263e0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
263f0 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
26400 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
26410 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72  () then that par
26420 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
26430 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
26440 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
26450 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
26460 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
26470 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
26480 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
26490 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
264a0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
264b0 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
264c0 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
264d0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
264e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
264f0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
26500 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
26510 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
26520 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
26530 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
26540 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
26550 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
26560 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
26570 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
26580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
26590 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
265a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
265b0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
265c0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
265d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
265e0 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
265f0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
26600 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
26610 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
26620 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
26630 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
26640 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
26650 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
26660 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
26670 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
26680 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
26690 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
266a0 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
266b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
266c0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
266d0 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
266e0 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
266f0 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
26700 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
26710 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
26720 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
26730 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
26740 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
26750 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
26760 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
26770 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
26780 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
26790 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
267a0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
267b0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
267c0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
267d0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
267e0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
267f0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
26800 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
26810 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
26820 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
26830 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
26840 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26850 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
26860 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
26870 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
26880 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
26890 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
268a0 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
268b0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
268c0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
268d0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
268e0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
268f0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
26900 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
26910 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
26920 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
26930 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
26940 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
26950 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
26960 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
26970 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
26980 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
26990 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
269a0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
269b0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
269c0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
269d0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
269e0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
269f0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
26a00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
26a10 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
26a20 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
26a30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
26a40 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
26a50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
26a60 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
26a70 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
26a80 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
26a90 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
26aa0 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
26ab0 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
26ac0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
26ad0 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
26ae0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
26af0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
26b00 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
26b10 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
26b20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
26b30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26b40 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
26b50 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
26b60 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
26b70 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
26b80 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
26b90 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
26ba0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
26bb0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
26bc0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
26bd0 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
26be0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
26bf0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
26c00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26c10 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
26c20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
26c30 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
26c40 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
26c50 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
26c60 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
26c70 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
26c80 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
26c90 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
26ca0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
26cb0 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
26cc0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
26cd0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
26ce0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
26cf0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
26d00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
26d10 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
26d20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
26d30 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
26d40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
26d50 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
26d60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
26d70 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26d80 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
26d90 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
26da0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
26db0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
26dc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
26dd0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
26de0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
26df0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
26e00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
26e10 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
26e20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26e30 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
26e40 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
26e50 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
26e60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
26e70 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
26e80 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
26e90 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
26ea0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26eb0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
26ec0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26ed0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
26ee0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
26ef0 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
26f00 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
26f10 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
26f20 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
26f30 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
26f40 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
26f50 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
26f60 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
26f70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
26f80 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
26f90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
26fa0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
26fb0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
26fc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
26fd0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
26fe0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
26ff0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
27000 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
27010 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
27020 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
27030 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
27040 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
27050 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
27060 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
27070 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27080 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
27090 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
270a0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
270b0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
270c0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
270d0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
270e0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
270f0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
27100 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
27110 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
27120 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
27130 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
27140 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
27150 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
27160 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
27170 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
27180 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
27190 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
271a0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
271b0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
271c0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
271d0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
271e0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
271f0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
27200 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
27210 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
27220 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
27230 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
27240 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
27250 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
27260 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
27270 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
27280 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
27290 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
272a0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
272b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
272c0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
272d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
272e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
272f0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
27300 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
27310 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
27320 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
27330 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
27340 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
27350 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
27360 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27370 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
27380 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
27390 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
273a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
273b0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
273c0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
273d0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
273e0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
273f0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
27400 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
27410 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
27420 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
27430 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
27440 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
27450 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
27460 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
27470 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
27480 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
27490 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
274a0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
274b0 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
274c0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
274d0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
274e0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
274f0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
27500 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
27510 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
27520 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
27530 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
27540 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
27550 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
27560 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
27570 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
27580 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
27590 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
275a0 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
275b0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
275c0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
275d0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
275e0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
275f0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
27600 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
27610 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
27620 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
27630 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
27640 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
27650 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
27660 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
27670 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
27680 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
27690 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
276a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
276b0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
276c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
276d0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
276e0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
276f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27700 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
27710 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
27720 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27730 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
27740 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
27750 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
27760 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
27770 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
27780 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
27790 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
277a0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
277b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
277c0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
277d0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
277e0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
277f0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
27800 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
27810 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
27820 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
27830 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
27840 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
27850 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
27860 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
27870 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
27880 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
27890 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
278a0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
278b0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
278c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
278d0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
278e0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
278f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27900 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
27910 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
27920 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
27930 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
27940 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
27950 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
27960 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
27970 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
27980 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
27990 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
279a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
279b0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
279c0 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
279d0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
279e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
279f0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
27a00 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
27a10 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
27a20 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
27a30 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
27a40 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
27a50 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
27a60 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
27a70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
27a80 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
27a90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27aa0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
27ab0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
27ac0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
27ad0 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
27ae0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
27af0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
27b00 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
27b10 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
27b20 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
27b30 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
27b40 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
27b50 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
27b60 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
27b70 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
27b80 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
27b90 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
27ba0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
27bb0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
27bc0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
27bd0 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
27be0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
27bf0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
27c00 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
27c10 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
27c20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27c30 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
27c40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
27c50 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
27c60 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
27c70 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27c80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
27c90 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
27ca0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
27cb0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
27cc0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
27cd0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
27ce0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
27cf0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
27d00 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
27d10 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
27d20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
27d30 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
27d40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27d50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
27d60 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
27d70 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
27d80 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
27d90 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
27da0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
27db0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
27dc0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
27dd0 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
27de0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
27df0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27e00 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
27e10 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
27e20 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
27e30 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
27e40 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
27e50 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
27e60 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
27e70 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
27e80 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
27e90 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
27ea0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
27eb0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
27ec0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27ed0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
27ee0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
27ef0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
27f00 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
27f10 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
27f20 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
27f30 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
27f40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27f50 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
27f60 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
27f70 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
27f80 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
27f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
27fa0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
27fb0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
27fc0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
27fd0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
27fe0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
27ff0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
28000 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
28010 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
28020 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
28030 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
28040 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
28050 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
28060 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
28070 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
28080 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
28090 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
280a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
280b0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
280c0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
280d0 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
280e0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
280f0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
28100 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
28110 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
28120 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
28130 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
28140 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
28150 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
28160 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
28170 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
28180 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28190 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
281a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
281b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
281c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
281d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
281e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
281f0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
28200 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
28210 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
28220 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
28230 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
28240 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
28250 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
28260 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
28270 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
28280 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
28290 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
282a0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
282b0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
282c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
282d0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
282e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
282f0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
28300 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
28310 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
28320 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
28330 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
28340 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
28350 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
28360 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
28370 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
28380 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
28390 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
283a0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
283b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
283c0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
283d0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
283e0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
283f0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
28400 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
28410 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
28420 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
28430 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
28440 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
28450 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
28460 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
28470 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
28480 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
28490 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
284a0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
284b0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
284c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
284d0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
284e0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
284f0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
28500 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
28510 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
28520 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
28530 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
28540 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
28550 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
28560 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
28570 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
28580 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
28590 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
285a0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
285b0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
285c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
285d0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
285e0 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
285f0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
28600 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
28610 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
28620 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
28630 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
28640 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
28650 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
28660 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
28670 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
28680 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
28690 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
286a0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
286b0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
286c0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
286d0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
286e0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
286f0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
28700 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
28710 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
28720 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
28730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
28740 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
28750 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
28760 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
28770 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
28780 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
28790 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
287a0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
287b0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
287c0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
287d0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
287e0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
287f0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
28800 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
28810 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
28820 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
28830 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
28840 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
28850 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
28860 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
28870 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
28880 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
28890 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
288a0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
288b0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
288c0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
288d0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
288e0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
288f0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
28900 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
28910 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
28920 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
28930 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
28940 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
28950 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
28960 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
28970 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
28980 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
28990 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
289a0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
289b0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
289c0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
289d0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
289e0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
289f0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
28a00 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
28a10 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
28a20 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
28a30 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
28a40 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
28a50 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
28a60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
28a70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28a80 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
28a90 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
28aa0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
28ab0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
28ac0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28ad0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
28ae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
28af0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
28b00 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28b10 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
28b20 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
28b30 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
28b40 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
28b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
28b60 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
28b70 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
28b80 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
28b90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
28ba0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
28bb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
28bc0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
28bd0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28be0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
28bf0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
28c00 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
28c10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
28c20 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
28c30 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
28c40 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
28c50 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
28c60 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
28c70 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
28c80 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
28c90 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
28ca0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
28cb0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
28cc0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
28cd0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
28ce0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
28cf0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
28d00 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
28d10 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
28d20 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
28d30 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
28d40 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
28d50 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
28d60 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
28d70 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
28d80 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
28d90 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
28da0 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
28db0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
28dc0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
28dd0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
28de0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
28df0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
28e00 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
28e10 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
28e20 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
28e30 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
28e40 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
28e50 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
28e60 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
28e70 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
28e80 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
28e90 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
28ea0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
28eb0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
28ec0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
28ed0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
28ee0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
28ef0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
28f00 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
28f10 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
28f20 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
28f30 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
28f40 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
28f50 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
28f60 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
28f70 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
28f80 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
28f90 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
28fa0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
28fb0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
28fc0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
28fd0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
28fe0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
28ff0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
29000 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
29010 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
29020 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
29030 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
29040 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
29050 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
29060 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
29070 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
29080 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
29090 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c  e values..*/.SQL
290a0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
290b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
290c0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
290d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
290e0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
290f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29100 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
29110 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
29120 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
29130 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
29140 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
29150 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
29160 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29170 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
29180 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
29190 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
291a0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
291b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
291c0 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
291d0 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
291e0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
291f0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
29200 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29210 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
29220 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
29230 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
29240 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
29250 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
29260 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
29270 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
29280 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
29290 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
292a0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
292b0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
292c0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
292d0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
292e0 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
292f0 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
29300 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29310 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
29320 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
29330 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
29340 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
29350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
29360 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
29370 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
29380 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
29390 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
293a0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
293b0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
293c0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
293d0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
293e0 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
293f0 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
29400 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
29410 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
29420 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
29430 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
29440 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
29450 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
29460 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
29470 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
29480 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
29490 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
294a0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
294b0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
294c0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
294d0 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
294e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
294f0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
29500 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
29510 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
29520 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
29530 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
29540 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
29550 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
29560 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
29570 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
29580 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
29590 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
295a0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
295b0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
295c0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
295d0 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
295e0 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
295f0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
29600 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
29610 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
29620 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
29630 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
29640 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
29650 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
29660 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
29670 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
29680 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
29690 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
296a0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
296b0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
296c0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
296d0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
296e0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
296f0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
29700 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
29710 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
29720 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
29730 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
29740 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
29750 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
29760 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
29770 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
29780 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
29790 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
297a0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
297b0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
297c0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
297d0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
297e0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
297f0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
29800 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
29810 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
29820 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
29830 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
29840 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
29850 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
29860 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
29870 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
29880 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
29890 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
298a0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
298b0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
298c0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
298d0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
298e0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
298f0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
29900 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
29910 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
29920 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
29930 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
29940 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
29950 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
29960 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
29970 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
29980 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
29990 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
299a0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
299b0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
299c0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
299d0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
299e0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
299f0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
29a00 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
29a10 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
29a20 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
29a30 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29a40 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
29a50 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
29a60 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
29a70 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
29a80 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
29a90 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
29aa0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
29ab0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
29ac0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
29ad0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
29ae0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
29af0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
29b00 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
29b10 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
29b20 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
29b30 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
29b40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
29b50 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
29b60 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
29b70 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
29b80 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
29b90 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
29ba0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
29bb0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
29bc0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
29bd0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
29be0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
29bf0 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
29c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29c10 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
29c20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
29c30 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
29c40 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
29c50 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
29c60 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
29c70 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
29c80 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
29c90 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
29ca0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29cb0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
29cc0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
29cd0 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
29ce0 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
29cf0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
29d00 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
29d10 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
29d20 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
29d30 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
29d40 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
29d50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29d60 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
29d70 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
29d80 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
29d90 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
29da0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
29db0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
29dc0 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
29dd0 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
29de0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
29df0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
29e00 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
29e10 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
29e20 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
29e30 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
29e40 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
29e50 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
29e60 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
29e70 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
29e80 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
29e90 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
29ea0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
29eb0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
29ec0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
29ed0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
29ee0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
29ef0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
29f00 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
29f10 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
29f20 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
29f30 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
29f40 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
29f50 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
29f60 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
29f70 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
29f80 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
29f90 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
29fa0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
29fb0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
29fc0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
29fd0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
29fe0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
29ff0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
2a000 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
2a010 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
2a020 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
2a030 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2a040 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a050 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
2a060 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
2a070 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
2a080 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
2a090 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
2a0a0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
2a0b0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
2a0c0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
2a0d0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
2a0e0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
2a0f0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
2a100 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
2a110 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
2a120 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
2a130 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
2a140 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
2a150 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2a160 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2a170 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
2a180 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
2a190 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
2a1a0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2a1b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2a1c0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
2a1d0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
2a1e0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2a1f0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
2a200 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
2a210 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2a220 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
2a230 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2a240 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2a250 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2a260 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2a270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2a280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a290 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2a2a0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2a2b0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2a2c0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2a2d0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
2a2e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2a2f0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2a300 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2a310 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2a320 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2a330 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2a340 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2a350 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2a360 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2a370 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2a380 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2a390 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2a3a0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2a3b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2a3c0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2a3d0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2a3e0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2a3f0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2a400 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2a410 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2a420 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2a430 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2a440 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
2a450 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2a460 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
2a470 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
2a480 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
2a490 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2a4a0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
2a4b0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
2a4c0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2a4d0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
2a4e0 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
2a4f0 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
2a500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2a510 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
2a520 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
2a530 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
2a540 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
2a550 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
2a560 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
2a570 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2a580 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
2a590 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
2a5a0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
2a5b0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
2a5c0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
2a5d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a5e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2a5f0 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
2a600 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2a610 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
2a620 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2a630 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a640 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
2a650 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
2a660 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
2a670 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
2a680 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2a690 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2a6a0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2a6b0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2a6c0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2a6d0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2a6e0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2a6f0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2a700 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2a710 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2a720 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2a730 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
2a740 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2a750 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
2a760 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
2a770 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
2a780 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
2a790 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
2a7a0 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
2a7b0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2a7c0 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
2a7d0 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
2a7e0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
2a7f0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
2a800 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
2a810 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
2a820 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
2a830 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
2a840 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
2a850 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
2a860 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2a870 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
2a880 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
2a890 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
2a8a0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
2a8b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a8c0 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
2a8d0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
2a8e0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
2a8f0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
2a900 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
2a910 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
2a920 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
2a930 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
2a940 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
2a950 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
2a960 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
2a970 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2a980 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
2a990 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
2a9a0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
2a9b0 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
2a9c0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2a9d0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2a9e0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2a9f0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2aa00 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2aa10 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2aa20 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2aa30 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2aa40 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2aa50 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2aa60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2aa70 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2aa80 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2aa90 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2aaa0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2aab0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2aac0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2aad0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2aae0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2aaf0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2ab00 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2ab10 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2ab20 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2ab30 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2ab40 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2ab50 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2ab60 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2ab70 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2ab80 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2ab90 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2aba0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2abb0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2abc0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2abd0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2abe0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2abf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2ac00 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2ac10 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2ac20 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2ac30 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2ac40 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2ac50 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2ac60 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2ac70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2ac80 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2ac90 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2aca0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2acb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2acc0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2acd0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2ace0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2acf0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2ad00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ad10 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2ad20 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2ad30 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2ad40 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ad50 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2ad60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ad70 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2ad80 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2ad90 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2ada0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2adb0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2adc0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2add0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2ade0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2adf0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2ae00 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2ae10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ae20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2ae30 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2ae40 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2ae50 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2ae60 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2ae70 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2ae80 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2ae90 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2aea0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2aeb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2aec0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2aed0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2aee0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2aef0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2af00 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2af10 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2af20 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2af30 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2af40 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2af50 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2af60 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2af70 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2af80 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2af90 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2afa0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2afb0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2afc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2afd0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2afe0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2aff0 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2b000 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
2b010 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
2b020 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
2b030 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
2b040 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
2b050 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
2b060 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2b070 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
2b080 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
2b090 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2b0a0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
2b0b0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
2b0c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2b0d0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
2b0e0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
2b0f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2b100 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2b110 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2b120 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2b130 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2b140 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2b150 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2b160 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2b170 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2b180 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2b190 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
2b1a0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2b1b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2b1c0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2b1d0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
2b1e0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2b1f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b200 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2b210 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2b220 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2b230 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b240 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2b250 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2b260 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2b270 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2b280 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2b290 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2b2a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2b2b0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2b2c0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2b2d0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2b2e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b2f0 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
2b300 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
2b310 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2b320 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
2b330 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2b340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b350 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
2b360 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2b370 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2b380 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2b390 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2b3a0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2b3b0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
2b3c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b3d0 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
2b3e0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2b3f0 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
2b400 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2b410 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2b420 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2b430 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2b440 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2b450 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b460 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2b470 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2b480 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2b490 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
2b4a0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
2b4b0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2b4c0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2b4d0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2b4e0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2b4f0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2b500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b510 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
2b520 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
2b530 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2b540 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b550 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
2b560 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2b570 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
2b580 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2b590 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
2b5a0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2b5b0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
2b5c0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
2b5d0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2b5e0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2b5f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2b600 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2b610 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
2b620 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
2b630 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
2b640 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
2b650 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2b660 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
2b670 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2b680 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2b690 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2b6a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2b6b0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2b6c0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2b6d0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
2b6e0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
2b6f0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
2b700 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
2b710 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
2b720 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
2b730 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2b740 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  r..**.** ^The ob
2b750 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2b760 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b770 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2b780 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2b790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b7a0 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
2b7b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b7c0 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
2b7d0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2b7e0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
2b7f0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
2b800 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2b810 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
2b820 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
2b830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2b840 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2b850 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2b860 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2b870 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
2b880 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
2b890 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
2b8a0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2b8b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2b8c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2b8d0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2b8e0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2b8f0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
2b900 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2b910 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2b920 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2b930 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
2b940 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
2b950 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
2b960 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
2b970 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
2b980 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
2b990 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
2b9a0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
2b9b0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
2b9c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2b9d0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
2b9e0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
2b9f0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
2ba00 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
2ba10 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
2ba20 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
2ba30 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
2ba40 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
2ba50 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
2ba60 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2ba70 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2ba80 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
2ba90 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
2baa0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
2bab0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
2bac0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
2bad0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2bae0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
2baf0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
2bb00 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2bb10 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2bb20 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
2bb30 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2bb40 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
2bb50 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
2bb60 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2bb70 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2bb80 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2bb90 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2bba0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2bbb0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2bbc0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
2bbd0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2bbe0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
2bbf0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
2bc00 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2bc10 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2bc20 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2bc30 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
2bc40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2bc50 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
2bc60 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2bc70 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
2bc80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2bc90 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
2bca0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2bcb0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
2bcc0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2bcd0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2bce0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2bcf0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2bd00 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
2bd10 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2bd20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2bd30 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
2bd40 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
2bd50 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2bd60 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2bd70 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
2bd80 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2bd90 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2bda0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
2bdb0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
2bdc0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2bdd0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2bde0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2bdf0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2be00 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2be10 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2be20 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
2be30 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2be40 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2be50 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2be60 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2be70 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2be80 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2be90 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2bea0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
2beb0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
2bec0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2bed0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
2bee0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2bef0 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2bf00 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2bf10 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2bf20 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2bf30 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2bf40 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2bf50 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2bf60 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2bf70 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2bf80 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2bf90 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2bfa0 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2bfb0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2bfc0 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2bfd0 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2bfe0 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2bff0 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2c000 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2c010 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2c020 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2c030 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2c040 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2c050 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2c060 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2c070 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2c080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c090 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2c0a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c0b0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2c0c0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2c0d0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2c0e0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2c0f0 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2c100 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2c110 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2c120 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2c130 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2c140 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2c150 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2c160 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2c170 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2c180 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2c190 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2c1a0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2c1b0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2c1c0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2c1d0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2c1e0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2c1f0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2c200 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2c210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c220 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2c230 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c240 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2c250 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2c260 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2c270 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2c280 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2c290 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2c2a0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2c2b0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2c2c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c2d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2c2e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c2f0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2c300 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2c310 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2c320 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2c330 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2c340 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
2c350 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
2c360 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
2c370 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
2c380 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
2c390 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
2c3a0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
2c3b0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
2c3c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2c3d0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
2c3e0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
2c3f0 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
2c400 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
2c410 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
2c420 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
2c430 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
2c440 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
2c450 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
2c460 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
2c470 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
2c480 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
2c490 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
2c4a0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
2c4b0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
2c4c0 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
2c4d0 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
2c4e0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
2c4f0 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
2c500 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
2c510 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
2c520 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
2c530 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2c540 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
2c550 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2c560 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c570 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2c580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2c590 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
2c5a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c5b0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2c5c0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2c5d0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
2c5e0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2c5f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2c600 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2c610 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
2c620 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
2c630 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
2c640 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
2c650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c660 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
2c670 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2c680 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
2c690 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
2c6a0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
2c6b0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
2c6c0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
2c6d0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2c6e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c6f0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
2c700 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
2c710 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
2c720 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
2c730 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c740 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2c750 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2c760 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
2c770 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c780 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
2c790 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
2c7a0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2c7b0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
2c7c0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
2c7d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c7e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
2c7f0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2c800 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
2c810 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2c820 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
2c830 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
2c840 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
2c850 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2c860 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c870 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2c880 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2c890 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
2c8a0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
2c8b0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
2c8c0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
2c8d0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
2c8e0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
2c8f0 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
2c900 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
2c910 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c920 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2c930 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2c940 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
2c950 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2c960 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
2c970 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2c980 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2c990 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2c9a0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2c9b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2c9c0 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2c9d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2c9e0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2c9f0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2ca00 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2ca10 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2ca20 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2ca30 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2ca40 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2ca50 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2ca60 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2ca70 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2ca80 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51  _NOMEM].)^.*/.SQ
2ca90 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2caa0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2cab0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2cac0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2cad0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2cae0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2caf0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2cb00 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2cb10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2cb20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cb30 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
2cb40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2cb50 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
2cb60 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2cb70 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2cb80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2cb90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2cba0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2cbb0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2cbc0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2cbd0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
2cbe0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2cbf0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
2cc00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2cc10 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2cc20 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
2cc30 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2cc40 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2cc50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2cc60 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2cc70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2cc80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2cc90 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2cca0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2ccb0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ccc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2ccd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2cce0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2ccf0 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  API sqlite3_valu
2cd00 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
2cd10 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
2cd20 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2cd30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cd40 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
2cd50 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2cd60 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
2cd70 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2cd80 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
2cd90 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
2cda0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
2cdb0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
2cdc0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2cdd0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
2cde0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
2cdf0 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
2ce00 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
2ce10 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
2ce20 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
2ce30 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
2ce40 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
2ce50 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
2ce60 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
2ce70 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2ce80 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
2ce90 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
2cea0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ceb0 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
2cec0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
2ced0 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
2cee0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
2cef0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2cf00 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2cf10 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
2cf20 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
2cf30 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
2cf40 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
2cf50 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2cf60 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
2cf70 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
2cf80 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
2cf90 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
2cfa0 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
2cfb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2cfc0 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
2cfd0 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
2cfe0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
2cff0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
2d000 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
2d010 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
2d020 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
2d030 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
2d040 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
2d050 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
2d060 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
2d070 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
2d080 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
2d090 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
2d0a0 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
2d0b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
2d0c0 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
2d0d0 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
2d0e0 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
2d0f0 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
2d100 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2d110 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
2d120 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2d130 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2d140 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2d150 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
2d160 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d170 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2d180 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2d190 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
2d1a0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
2d1b0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
2d1c0 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
2d1d0 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
2d1e0 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
2d1f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d200 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d210 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2d220 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2d230 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
2d240 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2d250 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2d260 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
2d270 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
2d280 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
2d290 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2d2a0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2d2b0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2d2c0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
2d2d0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
2d2e0 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
2d2f0 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2d300 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2d310 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2d320 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2d330 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2d340 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2d350 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2d360 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2d370 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2d380 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2d390 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2d3a0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
2d3b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2d3c0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2d3d0 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
2d3e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d3f0 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
2d400 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
2d410 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
2d420 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2d430 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2d440 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2d450 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2d460 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d470 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2d480 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2d490 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
2d4a0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2d4b0 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2d4c0 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2d4d0 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
2d4e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2d4f0 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2d500 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
2d510 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2d520 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d530 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2d540 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2d550 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2d560 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2d570 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
2d580 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2d590 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
2d5a0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2d5b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2d5c0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2d5d0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
2d5e0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
2d5f0 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
2d600 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d610 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
2d620 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2d630 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51  tement] S..*/.SQ
2d640 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2d650 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
2d660 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d680 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
2d690 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
2d6a0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
2d6b0 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
2d6c0 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
2d6d0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2d6e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2d6f0 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
2d700 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2d710 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2d720 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
2d730 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2d740 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
2d750 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
2d760 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2d770 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
2d780 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
2d790 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2d7a0 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
2d7b0 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
2d7c0 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
2d7d0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
2d7e0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
2d7f0 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
2d800 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a  rences between.*
2d810 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * these routines
2d820 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
2d830 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20  coding expected 
2d840 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  for.** the secon
2d850 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  d parameter (the
2d860 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e   name of the fun
2d870 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61  ction being crea
2d880 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ted).** and the 
2d890 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65  presence or abse
2d8a0 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63  nce of a destruc
2d8b0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  tor callback for
2d8c0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2d8d0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2d8e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2d8f0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2d900 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2d910 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
2d920 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
2d930 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
2d940 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
2d950 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
2d960 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
2d970 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2d980 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
2d990 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2d9a0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
2d9b0 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
2d9c0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
2d9d0 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
2d9e0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ely..**.** ^The 
2d9f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2da00 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2da10 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2da20 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
2da30 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
2da40 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
2da50 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
2da60 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
2da70 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72   in a UTF-8.** r
2da80 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65  epresentation, e
2da90 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
2daa0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
2dab0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65    ^Note that the
2dac0 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20   name.** length 
2dad0 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d  limit is in UTF-
2dae0 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61  8 bytes, not cha
2daf0 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d  racters nor UTF-
2db00 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e  16 bytes.  .** ^
2db10 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
2db20 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
2db30 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
2db40 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
2db50 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  lt in [SQLITE_MI
2db60 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75  SUSE] being retu
2db70 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2db80 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2db90 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
2dba0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
2dbb0 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
2dbc0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2dbd0 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
2dbe0 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61  s. ^If this para
2dbf0 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65  meter is -1, the
2dc00 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
2dc10 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2dc20 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
2dc30 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2dc40 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e  nts between 0 an
2dc50 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73  d the limit.** s
2dc60 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  et by [sqlite3_l
2dc70 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2dc80 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2dc90 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  ]).  If the thir
2dca0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
2dcb0 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f  s less than -1 o
2dcc0 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
2dcd0 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  27 then the beha
2dce0 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
2dcf0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2dd00 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2dd10 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
2dd20 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
2dd30 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
2dd40 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
2dd50 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
2dd60 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
2dd70 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45  s parameters.  E
2dd80 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f  very SQL functio
2dd90 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2dda0 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f   must be able to
2ddb0 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54   work.** with UT
2ddc0 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
2ddd0 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
2dde0 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
2ddf0 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
2de00 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
2de10 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
2de20 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
2de30 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
2de40 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
2de50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2de60 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
2de70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2de80 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
2de90 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
2dea0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2deb0 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
2dec0 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
2ded0 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
2dee0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2def0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2df00 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
2df10 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
2df20 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
2df30 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
2df40 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
2df50 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
2df60 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
2df70 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
2df80 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
2df90 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
2dfa0 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
2dfb0 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
2dfc0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
2dfd0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
2dfe0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
2dff0 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
2e000 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
2e010 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
2e020 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
2e030 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
2e040 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
2e050 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
2e060 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
2e070 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
2e080 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2e090 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
2e0a0 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
2e0b0 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
2e0c0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
2e0d0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
2e0e0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
2e0f0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
2e100 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
2e110 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2e120 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2e130 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
2e140 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
2e150 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2e160 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2e170 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
2e180 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
2e190 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
2e1a0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
2e1b0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
2e1c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
2e1d0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
2e1e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2e1f0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2e200 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
2e210 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
2e220 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
2e230 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
2e240 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
2e250 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
2e260 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2e270 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
2e280 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
2e290 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
2e2a0 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
2e2b0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
2e2c0 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
2e2d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
2e2e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2e2f0 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
2e300 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
2e310 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
2e320 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2e330 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
2e340 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2e350 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
2e360 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
2e370 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
2e380 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
2e390 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
2e3a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2e3b0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
2e3c0 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
2e3d0 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
2e3e0 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
2e3f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
2e400 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
2e410 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
2e420 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2e430 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
2e440 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
2e450 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
2e460 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
2e470 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
2e480 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
2e490 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e4a0 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
2e4b0 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
2e4c0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2e4d0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
2e4e0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
2e4f0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
2e500 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
2e510 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
2e520 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2e530 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
2e540 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
2e550 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
2e560 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
2e570 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
2e580 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
2e590 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
2e5a0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
2e5b0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
2e5c0 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
2e5d0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
2e5e0 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
2e5f0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
2e600 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
2e610 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
2e620 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
2e630 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2e640 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
2e650 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
2e660 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
2e670 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2e680 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2e690 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
2e6a0 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
2e6b0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2e6c0 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
2e6d0 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
2e6e0 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
2e6f0 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
2e700 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
2e710 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2e720 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
2e730 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2e740 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
2e750 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
2e760 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
2e770 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
2e780 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
2e790 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
2e7a0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2e7b0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2e7c0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
2e7d0 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
2e7e0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
2e7f0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
2e800 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
2e810 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
2e820 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
2e830 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2e840 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
2e850 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2e860 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
2e870 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
2e880 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
2e890 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
2e8a0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
2e8b0 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
2e8c0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
2e8d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
2e8e0 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
2e8f0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
2e900 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
2e910 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
2e920 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
2e930 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2e940 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e950 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
2e960 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2e970 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
2e980 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2e990 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2e9a0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2e9b0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2e9c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e9d0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2e9e0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2e9f0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2ea00 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2ea10 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2ea20 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2ea30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2ea40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2ea50 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2ea60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
2ea70 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2ea80 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
2ea90 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2eaa0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2eab0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2eac0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2ead0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2eae0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2eaf0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2eb00 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2eb10 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2eb20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2eb30 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2eb40 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2eb50 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
2eb60 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
2eb70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2eb80 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2eb90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2eba0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2ebb0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2ebc0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2ebd0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2ebe0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2ebf0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2ec00 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2ec10 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2ec20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2ec30 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2ec40 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2ec50 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2ec60 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
2ec70 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2ec80 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2ec90 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2eca0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
2ecb0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2ecc0 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2ecd0 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2ece0 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2ecf0 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2ed00 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2ed10 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2ed20 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2ed30 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2ed40 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2ed50 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2ed60 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2ed70 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2ed80 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2ed90 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2eda0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2edb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2edc0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2edd0 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2ede0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2edf0 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2ee00 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2ee10 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2ee20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ee30 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2ee40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ee50 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
2ee60 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
2ee70 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
2ee80 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
2ee90 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
2eea0 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
2eeb0 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
2eec0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
2eed0 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
2eee0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
2eef0 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
2ef00 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
2ef10 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
2ef20 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
2ef30 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2ef40 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2ef50 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2ef60 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2ef70 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2ef80 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2ef90 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2efa0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
2efb0 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
2efc0 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
2efd0 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
2efe0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
2eff0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2f000 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f010 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
2f020 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
2f030 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
2f040 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2f050 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2f060 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2f070 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
2f080 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2f090 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
2f0a0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2f0b0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
2f0c0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
2f0d0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2f0e0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
2f0f0 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
2f100 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
2f110 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2f120 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
2f130 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2f140 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
2f150 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2f160 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
2f170 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
2f180 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
2f190 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
2f1a0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
2f1b0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2f1c0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
2f1d0 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
2f1e0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
2f1f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
2f200 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
2f210 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
2f220 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2f230 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
2f240 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
2f250 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
2f260 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
2f270 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
2f280 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
2f290 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
2f2a0 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
2f2b0 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
2f2c0 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
2f2d0 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
2f2e0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
2f2f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f300 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2f310 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f320 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
2f330 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
2f340 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2f350 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
2f360 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2f370 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
2f380 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
2f390 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
2f3a0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
2f3b0 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
2f3c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2f3d0 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
2f3e0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
2f3f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
2f400 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
2f410 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
2f420 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
2f430 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2f440 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
2f450 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
2f460 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2f470 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
2f480 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2f490 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
2f4a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f4b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2f4c0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
2f4d0 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
2f4e0 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
2f4f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f500 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
2f510 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
2f520 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
2f530 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2f540 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
2f550 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
2f560 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
2f570 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2f580 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
2f590 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
2f5a0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
2f5b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f5c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
2f5d0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
2f5e0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
2f5f0 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
2f600 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
2f610 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
2f620 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f630 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
2f640 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
2f650 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
2f660 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
2f670 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
2f680 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
2f690 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
2f6a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2f6b0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
2f6c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2f6d0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2f6e0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
2f6f0 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
2f700 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
2f710 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
2f720 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
2f730 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2f740 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
2f750 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2f760 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
2f770 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
2f780 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
2f790 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
2f7a0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
2f7b0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
2f7c0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
2f7d0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
2f7e0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
2f7f0 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
2f800 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
2f810 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
2f820 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
2f830 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
2f840 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
2f850 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
2f860 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
2f870 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
2f880 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
2f890 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
2f8a0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
2f8b0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
2f8c0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2f8d0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
2f8e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
2f8f0 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
2f900 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
2f910 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
2f920 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
2f930 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
2f940 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2f950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2f960 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
2f970 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
2f980 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
2f990 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
2f9a0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
2f9b0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
2f9c0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2f9d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2f9e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2f9f0 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
2fa00 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2fa10 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2fa20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2fa30 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
2fa40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2fa50 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2fa60 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2fa70 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
2fa80 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
2fa90 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
2faa0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
2fab0 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eters..*/.SQLITE
2fac0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2fad0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
2fae0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
2faf0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2fb00 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2fb10 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
2fb20 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2fb30 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2fb40 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
2fb50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2fb60 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
2fb70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
2fb80 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
2fb90 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2fba0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
2fbb0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
2fbc0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2fbd0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
2fbe0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
2fbf0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
2fc00 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2fc10 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
2fc20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
2fc30 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
2fc40 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2fc50 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2fc60 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2fc70 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
2fc80 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2fc90 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2fca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2fcb0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
2fcc0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2fcd0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2fce0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2fcf0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
2fd00 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2fd10 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
2fd20 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
2fd30 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2fd40 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2fd50 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2fd60 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2fd70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2fd80 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
2fd90 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
2fda0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
2fdb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2fdc0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2fdd0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
2fde0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
2fdf0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
2fe00 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
2fe10 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
2fe20 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
2fe30 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2fe40 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2fe50 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
2fe60 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
2fe70 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
2fe80 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
2fe90 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
2fea0 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
2feb0 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
2fec0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
2fed0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2fee0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
2fef0 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
2ff00 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
2ff10 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
2ff20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2ff30 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
2ff40 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2ff50 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
2ff60 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
2ff70 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
2ff80 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2ff90 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
2ffa0 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
2ffb0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
2ffc0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
2ffd0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
2ffe0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
2fff0 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
30000 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
30010 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
30020 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
30030 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
30040 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
30050 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
30060 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
30070 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
30080 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
30090 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
300a0 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
300b0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
300c0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
300d0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
300e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
300f0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
30100 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
30110 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
30120 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
30130 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30140 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
30150 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
30160 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
30170 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
30180 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
30190 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
301a0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
301b0 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
301c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
301d0 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
301e0 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
301f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30200 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
30210 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
30220 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
30230 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
30240 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
30250 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
30260 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
30270 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
30280 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
30290 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
302a0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
302b0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
302c0 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
302d0 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
302e0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
302f0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
30300 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
30310 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
30320 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
30330 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
30340 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
30350 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
30360 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
30370 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
30380 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
30390 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
303a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
303b0 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
303c0 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
303d0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
303e0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
303f0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
30400 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
30410 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
30420 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
30430 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
30440 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
30450 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
30460 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
30470 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
30480 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
30490 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
304a0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
304b0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
304c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
304d0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
304e0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
304f0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
30500 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
30510 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
30520 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30530 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
30540 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
30550 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
30560 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
30570 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
30580 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
30590 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
305a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
305b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
305c0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
305d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
305e0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
305f0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
30600 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
30610 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
30620 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
30630 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
30640 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
30650 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
30660 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
30670 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
30680 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30690 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
306a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
306b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
306c0 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
306d0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
306e0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
306f0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
30700 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
30710 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30720 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
30730 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
30740 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
30750 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
30760 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
30770 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
30780 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
30790 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
307a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
307b0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
307c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
307d0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
307e0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
307f0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
30800 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
30810 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
30820 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
30830 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  I sqlite3 *sqlit
30840 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
30850 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
30860 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
30870 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
30880 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
30890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
308a0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
308b0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
308c0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
308d0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
308e0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
308f0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
30900 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
30910 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
30920 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
30930 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
30940 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
30950 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
30960 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
30970 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
30980 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
30990 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
309a0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
309b0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
309c0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
309d0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
309e0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
309f0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
30a00 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
30a10 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
30a20 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
30a30 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
30a40 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
30a50 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
30a60 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
30a70 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
30a80 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
30a90 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
30aa0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
30ab0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
30ac0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
30ad0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
30ae0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
30af0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
30b00 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
30b10 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
30b20 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
30b30 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
30b40 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
30b50 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
30b60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
30b70 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
30b80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
30b90 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
30ba0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
30bb0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
30bc0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
30bd0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
30be0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
30bf0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
30c00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30c10 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
30c20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20  ^If no metadata 
30c30 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
30c40 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
30c50 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
30c60 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
30c70 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
30c80 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
30c90 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
30ca0 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
30cb0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
30cc0 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
30cd0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
30ce0 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
30cf0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
30d00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30d10 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
30d20 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
30d30 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
30d40 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
30d50 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
30d60 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
30d70 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
30d80 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
30d90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30da0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
30db0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
30dc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
30dd0 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
30de0 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
30df0 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
30e00 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
30e10 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  d..** ^If it is 
30e20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
30e30 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
30e40 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
30e50 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
30e60 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
30e70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
30e80 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
30e90 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
30ea0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
30eb0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
30ec0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
30ed0 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
30ee0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
30ef0 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
30f00 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
30f10 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
30f20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
30f30 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
30f40 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
30f50 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
30f60 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
30f70 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
30f80 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e  ^The only guaran
30f90 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
30fa0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
30fb0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
30fc0 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
30fd0 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
30fe0 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
30ff0 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
31000 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
31010 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
31020 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
31030 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
31040 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
31050 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
31060 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
31070 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
31080 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ters].)^.**.** T
31090 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
310a0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
310b0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
310c0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
310d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
310e0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
310f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
31100 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
31110 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
31120 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c  xt*, int N);.SQL
31130 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
31140 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
31150 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31160 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
31170 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
31180 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
31190 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
311a0 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
311b0 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
311c0 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
311d0 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
311e0 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
311f0 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
31200 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
31210 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
31220 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
31230 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
31240 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
31250 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
31260 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
31270 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
31280 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
31290 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
312a0 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
312b0 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
312c0 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
312d0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
312e0 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
312f0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
31300 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
31310 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
31320 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
31330 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
31340 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
31350 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
31360 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
31370 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
31380 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
31390 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
313a0 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
313b0 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
313c0 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
313d0 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
313e0 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
313f0 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
31400 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
31410 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
31420 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
31430 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
31440 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
31450 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
31460 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
31470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
31480 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
31490 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
314a0 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
314b0 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
314c0 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
314d0 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
314e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
314f0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
31500 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
31510 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
31520 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
31530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
31540 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
31550 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
31560 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
31570 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
31580 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
31590 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
315a0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
315b0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
315c0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
315d0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
315e0 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
315f0 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
31600 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
31610 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
31620 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
31630 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
31640 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
31650 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
31660 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
31670 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
31680 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
31690 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
316a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
316b0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
316c0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
316d0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
316e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
316f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
31700 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
31710 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
31720 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
31730 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
31740 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
31750 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
31760 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
31770 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
31780 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31790 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
317a0 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
317b0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
317c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
317d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
317e0 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
317f0 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
31800 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
31810 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
31820 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
31830 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
31840 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
31850 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31860 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
31870 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
31880 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
31890 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
318a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
318b0 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
318c0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
318d0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
318e0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
318f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31900 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31910 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
31920 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
31930 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
31940 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
31950 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
31960 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
31970 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
31980 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
31990 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
319a0 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
319b0 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
319c0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
319d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
319e0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
319f0 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
31a00 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
31a10 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
31a20 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
31a30 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
31a40 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
31a50 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
31a60 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
31a70 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
31a80 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
31a90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
31aa0 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
31ab0 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
31ac0 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
31ad0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
31ae0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31af0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
31b00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31b10 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
31b20 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
31b30 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
31b40 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
31b50 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
31b60 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
31b70 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
31b80 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
31b90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
31ba0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
31bb0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
31bc0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
31bd0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
31be0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
31bf0 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
31c00 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
31c10 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
31c20 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
31c30 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
31c40 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
31c50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31c60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
31c70 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
31c80 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
31c90 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
31ca0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
31cb0 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
31cc0 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
31cd0 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
31ce0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
31cf0 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
31d00 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
31d10 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
31d20 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
31d30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31d40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
31d50 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
31d60 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
31d70 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
31d80 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
31d90 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
31da0 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
31db0 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
31dc0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
31dd0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
31de0 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
31df0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
31e00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31e10 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
31e20 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
31e30 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
31e40 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
31e50 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
31e60 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31e70 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20  _error_toobig() 
31e80 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
31e90 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
31ea0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
31eb0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
31ec0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
31ed0 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
31ee0 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
31ef0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31f00 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20  t_error_nomem() 
31f10 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
31f20 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
31f30 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
31f40 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
31f50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31f60 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
31f70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31f80 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
31f90 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
31fa0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
31fb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31fc0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31fd0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
31fe0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
31ff0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
32000 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
32010 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
32020 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
32030 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
32040 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
32050 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
32060 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32070 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
32080 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
32090 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
320a0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
320b0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
320c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
320d0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
320e0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
320f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
32100 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
32110 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32120 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
32130 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32140 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32150 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
32160 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
32170 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32180 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
32190 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
321a0 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
321b0 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
321c0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
321d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
321e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
321f0 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
32200 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
32210 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
32220 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
32230 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
32240 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
32250 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
32260 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
32270 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
32280 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
32290 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
322a0 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
322b0 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
322c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
322d0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
322e0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
322f0 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
32300 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
32310 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
32320 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
32330 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
32340 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
32350 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
32360 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
32370 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
32380 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
32390 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
323a0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
323b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
323c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
323d0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
323e0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
323f0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
32400 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
32410 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
32420 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
32430 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
32440 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
32450 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
32460 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
32470 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
32480 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
32490 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
324a0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
324b0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
324c0 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
324d0 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
324e0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
324f0 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
32500 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
32510 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
32520 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
32530 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
32540 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
32550 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
32560 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
32570 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
32580 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
32590 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
325a0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
325b0 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
325c0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
325d0 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
325e0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
325f0 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
32600 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
32610 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
32620 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
32630 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
32640 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
32650 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
32660 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
32670 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
32680 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
32690 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
326a0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
326b0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
326c0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
326d0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
326e0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
326f0 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
32700 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
32710 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
32720 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
32730 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32740 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
32750 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
32760 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
32770 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
32780 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
32790 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
327a0 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
327b0 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
327c0 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
327d0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
327e0 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
327f0 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
32800 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
32810 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
32820 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
32830 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
32840 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
32850 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
32860 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
32870 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
32880 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32890 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
328a0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
328b0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
328c0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
328d0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
328e0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
328f0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
32900 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
32910 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
32920 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
32930 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
32940 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
32950 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
32960 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
32970 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
32980 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
32990 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
329a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
329b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
329c0 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
329d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
329e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
329f0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
32a00 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
32a10 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
32a20 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
32a30 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
32a40 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
32a50 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
32a60 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
32a70 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
32a80 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
32a90 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
32aa0 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
32ab0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
32ac0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
32ad0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
32ae0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
32af0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
32b00 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32b10 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
32b20 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
32b30 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
32b40 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32b50 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
32b60 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
32b70 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
32b80 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
32b90 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
32ba0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
32bb0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
32bc0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
32bd0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
32be0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
32bf0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
32c00 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
32c10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32c20 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
32c30 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
32c40 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
32c50 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
32c60 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
32c70 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  efined..*/.SQLIT
32c80 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
32c90 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
32ca0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32cb0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32cc0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
32cd0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
32ce0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32cf0 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
32d00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
32d10 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
32d20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32d30 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
32d40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
32d50 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53  t char*, int);.S
32d60 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
32d70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32d80 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
32d90 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
32da0 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  id*, int);.SQLIT
32db0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
32dc0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
32dd0 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
32de0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
32df0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
32e00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
32e10 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
32e20 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
32e30 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32e40 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
32e50 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
32e60 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
32e70 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
32e80 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
32e90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
32ea0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
32eb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32ec0 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
32ed0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
32ee0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
32ef0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32f00 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
32f10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32f20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
32f30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32f40 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
32f50 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
32f60 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
32f70 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
32f80 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32f90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32fa0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
32fb0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
32fc0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
32fd0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
32fe0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
32ff0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
33000 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33010 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33020 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
33030 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
33040 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33050 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
33060 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
33070 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
33080 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
33090 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
330a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
330b0 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
330c0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
330d0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
330e0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
330f0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
33100 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33110 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
33120 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
33130 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
33140 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
33150 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
33160 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
33170 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
33180 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
33190 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
331a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
331b0 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
331c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
331d0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
331e0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
331f0 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
33200 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
33210 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33220 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
33230 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33240 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
33250 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
33260 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
33270 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
33280 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33290 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
332a0 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
332b0 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
332c0 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
332d0 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
332e0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
332f0 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
33300 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
33310 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
33320 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
33330 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
33340 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
33350 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
33360 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
33370 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
33380 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
33390 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
333a0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
333b0 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
333c0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
333d0 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
333e0 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
333f0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
33400 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
33410 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
33420 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
33430 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
33440 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
33450 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
33460 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
33470 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
33480 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
33490 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
334a0 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
334b0 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
334c0 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
334d0 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
334e0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
334f0 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
33500 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
33510 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
33520 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
33530 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
33540 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
33550 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
33560 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
33570 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
33580 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
33590 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
335a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
335b0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
335c0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
335d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
335e0 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
335f0 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
33600 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
33610 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
33620 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
33630 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
33640 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
33650 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
33660 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
33670 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
33680 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
33690 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
336a0 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
336b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
336c0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
336d0 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
336e0 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
336f0 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
33700 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
33710 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
33720 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
33730 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
33740 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
33750 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
33760 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
33770 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
33780 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
33790 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
337a0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
337b0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
337c0 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
337d0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
337e0 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
337f0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
33800 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
33810 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
33820 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
33830 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
33840 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
33850 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
33860 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33870 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
33880 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
33890 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
338a0 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
338b0 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
338c0 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
338d0 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
338e0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
338f0 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
33900 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
33910 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33920 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75  must always retu
33930 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77  rn the same answ
33940 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20  er.** given the 
33950 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66  same inputs.  If
33960 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c   two or more col
33970 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
33980 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a   are registered.
33990 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63  ** to the same c
339a0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75  ollation name (u
339b0 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65  sing different e
339c0 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20  TextRep values) 
339d0 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74  then all.** must
339e0 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c   give an equival
339f0 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20  ent answer when 
33a00 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75  invoked with equ
33a10 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e  ivalent strings.
33a20 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  .** The collatin
33a30 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
33a40 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  obey the followi
33a50 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f  ng properties fo
33a60 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73  r all.** strings
33a70 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a   A, B, and C:.**
33a80 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
33a90 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d   If A==B then B=
33aa0 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =A..** <li> If A
33ab0 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65  ==B and B==C the
33ac0 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20  n A==C..** <li> 
33ad0 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42  If A&lt;B THEN B
33ae0 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49  &gt;A..** <li> I
33af0 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c  f A&lt;B and B&l
33b00 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e  t;C then A&lt;C.
33b10 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
33b20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  If a collating f
33b30 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e  unction fails an
33b40 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63  y of the above c
33b50 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
33b60 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67  hat.** collating
33b70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65   function is  re
33b80 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65  gistered and use
33b90 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
33ba0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
33bb0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
33bc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33bd0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33be0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
33bf0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
33c00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
33c10 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74  * with the addit
33c20 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65  ion that the xDe
33c30 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
33c40 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72  s invoked on pAr
33c50 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  g when.** the co
33c60 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33c70 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   is deleted..** 
33c80 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74  ^Collating funct
33c90 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64  ions are deleted
33ca0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
33cb0 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
33cc0 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74  er.** calls to t
33cd0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
33ce0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
33cf0 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  or when the.** [
33d00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33d10 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75  ion] is closed u
33d20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
33d30 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ose()]..**.** ^T
33d40 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
33d50 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f  back is <u>not</
33d60 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  u> called if the
33d70 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65   .** sqlite3_cre
33d80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33d90 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  () function fail
33da0 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  s.  Applications
33db0 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20   that invoke.** 
33dc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33dd0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69  ollation_v2() wi
33de0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44  th a non-NULL xD
33df0 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20  estroy argument 
33e00 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b  should .** check
33e10 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
33e20 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20   and dispose of 
33e30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33e40 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  data pointer.** 
33e50 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65  themselves rathe
33e60 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67  r than expecting
33e70 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20   SQLite to deal 
33e80 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d  with it for them
33e90 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66  ..** This is dif
33ea0 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72  ferent from ever
33eb0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
33ec0 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69  nterface.  The i
33ed0 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a  nconsistency .**
33ee0 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20   is unfortunate 
33ef0 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  but cannot be ch
33f00 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72  anged without br
33f10 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73  eaking backwards
33f20 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69   .** compatibili
33f30 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ty..**.** See al
33f40 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
33f50 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
33f60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
33f70 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
33f80 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  6()]..*/.SQLITE_
33f90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
33fa0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33fb0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
33fc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
33fd0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
33fe0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
33ff0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
34000 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
34010 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
34020 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53  onst void*).);.S
34030 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34040 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34050 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
34060 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
34070 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
34080 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
34090 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
340a0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
340b0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
340c0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
340d0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
340e0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
340f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34100 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34110 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
34120 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
34130 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
34140 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
34150 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
34160 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
34170 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
34180 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
34190 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
341a0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
341b0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
341c0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
341d0 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
341e0 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
341f0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
34200 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
34210 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
34220 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
34230 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
34240 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
34250 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
34260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34270 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
34280 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
34290 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
342a0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
342b0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
342c0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
342d0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
342e0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
342f0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
34300 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
34310 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
34320 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
34330 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
34340 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
34350 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
34360 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
34370 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34380 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
34390 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
343a0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
343b0 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
343c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
343d0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
343e0 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
343f0 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
34400 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
34410 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
34420 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
34430 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34440 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
34450 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
34460 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
34470 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
34480 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
34490 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
344a0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
344b0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
344c0 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
344d0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
344e0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
344f0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
34500 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
34510 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
34520 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
34530 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
34540 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
34550 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
34560 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
34570 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
34580 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
34590 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
345a0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
345b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
345c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
345d0 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
345e0 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
345f0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
34600 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
34610 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
34620 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
34630 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
34640 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34650 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
34660 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34670 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
34680 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34690 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
346a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
346b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
346c0 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
346d0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
346e0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
346f0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
34700 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
34710 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  ar*).);.SQLITE_A
34720 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
34730 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
34740 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
34750 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
34760 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
34770 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
34780 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
34790 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
347a0 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
347b0 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
347c0 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
347d0 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
347e0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
347f0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
34800 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
34810 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
34820 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
34830 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
34840 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
34850 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
34860 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
34870 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
34880 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
34890 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
348a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
348b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
348c0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
348d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
348e0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
348f0 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
34900 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
34910 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
34920 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
34930 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
34940 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
34950 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
34960 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
34970 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
34980 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
34990 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
349a0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
349b0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
349c0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
349d0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
349e0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
349f0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
34a00 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
34a10 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
34a20 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
34a30 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
34a40 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
34a50 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
34a60 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
34a70 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
34a80 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
34a90 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
34aa0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
34ab0 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
34ac0 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
34ad0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
34ae0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
34af0 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
34b00 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
34b10 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34b20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
34b30 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
34b40 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
34b50 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
34b60 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
34b70 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
34b80 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
34b90 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
34ba0 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
34bb0 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
34bc0 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
34bd0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
34be0 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
34bf0 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
34c00 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49  ll work..*/.SQLI
34c10 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
34c20 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
34c30 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
34c40 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
34c50 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
34c60 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
34c70 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
34c80 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
34c90 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
34ca0 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
34cb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
34cc0 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
34cd0 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
34ce0 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
34cf0 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
34d00 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
34d10 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
34d20 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
34d30 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
34d40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
34d50 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
34d60 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
34d70 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
34d80 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
34d90 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
34da0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
34db0 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
34dc0 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
34dd0 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
34de0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
34df0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
34e00 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
34e10 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
34e20 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
34e30 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
34e40 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69  .**.** ^SQLite i
34e50 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
34e60 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
34e70 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
34e80 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
34e90 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
34ea0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
34eb0 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29   If the xSleep()
34ec0 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
34ed0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
34ee0 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
34ef0 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e   correctly, or n
34f00 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  ot implemented a
34f10 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74  t.** all, then t
34f20 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
34f30 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d  qlite3_sleep() m
34f40 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20  ay deviate from 
34f50 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a  the description.
34f60 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ** in the previo
34f70 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a  us paragraphs..*
34f80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
34f90 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
34fa0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
34fb0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
34fc0 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
34fd0 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
34fe0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
34ff0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
35000 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
35010 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
35020 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
35030 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
35040 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
35050 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
35060 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
35070 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
35080 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
35090 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
350a0 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
350b0 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
350c0 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
350d0 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
350e0 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
350f0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
35100 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
35110 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
35120 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
35130 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
35140 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
35150 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
35160 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
35170 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
35180 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
35190 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
351a0 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
351b0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
351c0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
351d0 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
351e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
351f0 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
35200 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
35210 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
35220 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
35230 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
35240 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
35250 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
35260 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
35270 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
35280 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
35290 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
352a0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
352b0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
352c0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
352d0 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
352e0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
352f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
35300 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35310 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
35320 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
35330 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
35340 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
35350 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
35360 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
35370 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
35380 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
35390 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
353a0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
353b0 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
353c0 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
353d0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
353e0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
353f0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
35400 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
35410 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
35420 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
35430 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
35440 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
35450 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
35460 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
35470 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
35480 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
35490 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
354a0 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
354b0 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
354c0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
354d0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
354e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
354f0 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
35500 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
35510 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35520 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
35530 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
35540 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
35550 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
35560 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
35570 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
35580 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
35590 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
355a0 6c 64 69 6e 67 20 44 61 74 61 62 61 73 65 20 46  lding Database F
355b0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
355c0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
355d0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
355e0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
355f0 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
35600 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
35610 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
35620 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
35630 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a  database files.*
35640 2a 20 73 70 65 63 69 66 69 65 64 20 77 69 74 68  * specified with
35650 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
35660 6e 61 6d 65 20 61 6e 64 20 63 72 65 61 74 65 64  name and created
35670 20 6f 72 20 61 63 63 65 73 73 65 64 20 62 79 0a   or accessed by.
35680 2a 2a 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  ** SQLite when u
35690 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
356a0 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74 65 33  windows [sqlite3
356b0 5f 76 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c  _vfs | VFS] will
356c0 20 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74   be assumed.** t
356d0 6f 20 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f  o be relative to
356e0 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
356f0 29 5e 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  )^ ^If this vari
35700 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a  able is a NULL.*
35710 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  * pointer, then 
35720 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
35730 68 61 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65  hat all database
35740 20 66 69 6c 65 73 20 73 70 65 63 69 66 69 65 64   files specified
35750 0a 2a 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74  .** with a relat
35760 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65  ive pathname are
35770 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65   relative to the
35780 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
35790 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72  ry.** for the pr
357a0 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65  ocess.  Only the
357b0 20 77 69 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b   windows VFS mak
357c0 65 73 20 75 73 65 20 6f 66 20 74 68 69 73 20 67  es use of this g
357d0 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c  lobal.** variabl
357e0 65 3b 20 69 74 20 69 73 20 69 67 6e 6f 72 65 64  e; it is ignored
357f0 20 62 79 20 74 68 65 20 75 6e 69 78 20 56 46 53   by the unix VFS
35800 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67  ..**.** Changing
35810 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
35820 69 73 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c  is variable whil
35830 65 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  e a database con
35840 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70  nection is.** op
35850 65 6e 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  en can result in
35860 20 61 20 63 6f 72 72 75 70 74 20 64 61 74 61 62   a corrupt datab
35870 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ase..**.** It is
35880 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
35890 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
358a0 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
358b0 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
358c0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
358d0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
358e0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
358f0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
35900 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
35910 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
35920 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
35930 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
35940 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
35950 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
35960 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
35970 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
35980 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
35990 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
359a0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
359b0 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
359c0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
359d0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
359e0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
359f0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
35a00 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
35a10 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
35a20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61  **.** ^The [data
35a30 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35a40 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
35a50 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
35a60 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
35a70 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
35a80 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
35a90 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
35aa0 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
35ab0 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61  re,.** the [data
35ac0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35ad0 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
35ae0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
35af0 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
35b00 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
35b10 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
35b20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
35b30 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
35b40 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
35b50 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
35b60 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
35b70 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
35b80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
35b90 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
35ba0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
35bb0 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
35bc0 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
35bd0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
35be0 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
35bf0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
35c00 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
35c10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
35c20 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
35c30 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
35c40 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35c50 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
35c60 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
35c70 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
35c80 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
35c90 6c 69 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63  lite3_data_direc
35ca0 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
35cb0 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
35cc0 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
35cd0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
35ce0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
35cf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35d00 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
35d10 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
35d20 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
35d30 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
35d40 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
35d50 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
35d60 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
35d70 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
35d80 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
35d90 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
35da0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
35db0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
35dc0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
35dd0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
35de0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
35df0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35e00 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
35e10 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
35e20 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
35e30 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
35e40 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
35e50 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
35e60 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
35e70 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
35e80 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
35e90 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
35ea0 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
35eb0 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
35ec0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
35ed0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
35ee0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
35ef0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
35f00 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
35f10 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
35f20 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
35f30 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
35f40 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
35f50 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
35f60 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
35f70 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
35f80 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
35f90 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
35fa0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
35fb0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
35fc0 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
35fd0 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
35fe0 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
35ff0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
36000 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
36010 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
36020 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
36030 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
36040 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  efined..*/.SQLIT
36050 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
36060 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
36070 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
36080 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
36090 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48  d The Database H
360a0 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61  andle Of A Prepa
360b0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
360c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
360d0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
360e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
360f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36100 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
36110 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65   to which a [pre
36120 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36130 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20   belongs.  ^The 
36140 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36150 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  tion].** returne
36160 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f  d by sqlite3_db_
36170 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61  handle is the sa
36180 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
36190 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74  nection].** that
361a0 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61   was the first a
361b0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
361c0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
361d0 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f  re_v2()] call (o
361e0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  r its variants) 
361f0 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f  that was used to
36200 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73  .** create the s
36210 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
36220 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a  first place..*/.
36230 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
36240 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
36250 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
36260 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
36270 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68  I3REF: Return Th
36280 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41  e Filename For A
36290 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
362a0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
362b0 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e  sqlite3_db_filen
362c0 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61  ame(D,N) interfa
362d0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
362e0 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61  nter to a filena
362f0 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  me.** associated
36300 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20 4e   with database N
36310 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   of connection D
36320 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74  .  ^The main dat
36330 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61  abase file.** ha
36340 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e  s the name "main
36350 22 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  ".  If there is 
36360 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61 74 61  no attached data
36370 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61  base N on the da
36380 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
36390 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61  tion D, or if da
363a0 74 61 62 61 73 65 20 4e 20 69 73 20 61 20 74 65  tabase N is a te
363b0 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65  mporary or in-me
363c0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20 74  mory database, t
363d0 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  hen.** a NULL po
363e0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
363f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
36400 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20  lename returned 
36410 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
36420 20 69 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f   is the output o
36430 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61  f the.** xFullPa
36440 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66  thname method of
36450 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e   the [VFS].  ^In
36460 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
36470 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69  e filename.** wi
36480 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74  ll be an absolut
36490 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e  e pathname, even
364a0 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   if the filename
364b0 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e   used.** to open
364c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
364d0 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55  iginally was a U
364e0 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70  RI or relative p
364f0 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 53 51 4c 49  athname..*/.SQLI
36500 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
36510 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 69  r *sqlite3_db_fi
36520 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 2a  lename(sqlite3 *
36530 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  db, const char *
36540 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a  zDbName);../*.**
36550 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
36560 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61 62 61  mine if a databa
36570 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a  se is read-only.
36580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36590 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44  e3_db_readonly(D
365a0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
365b0 74 75 72 6e 73 20 31 20 69 66 20 74 68 65 20 64  turns 1 if the d
365c0 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20  atabase N.** of 
365d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73 20  connection D is 
365e0 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20  read-only, 0 if 
365f0 69 74 20 69 73 20 72 65 61 64 2f 77 72 69 74 65  it is read/write
36600 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20 69 73 20  , or -1 if N is 
36610 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  not.** the name 
36620 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  of a database on
36630 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
36640 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
36650 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64   sqlite3_db_read
36660 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20 2a 64 62  only(sqlite3 *db
36670 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44  , const char *zD
36680 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  bName);../*.** C
36690 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68  API3REF: Find th
366a0 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20  e next prepared 
366b0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  statement.**.** 
366c0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
366d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
366e0 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
366f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36700 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
36710 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
36720 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
36730 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
36740 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e    ^If pStmt is N
36750 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ULL.** then this
36760 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36770 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
36780 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72  the first prepar
36790 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
367a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
367b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
367c0 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49  nection pDb.  ^I
367d0 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74  f no prepared st
367e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73  atement.** satis
367f0 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
36800 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
36810 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ine, it returns 
36820 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
36830 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36840 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20  tion] pointer D 
36850 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  in a call to.** 
36860 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
36870 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65  mt(D,S)] must re
36880 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64  fer to an open d
36890 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
368a0 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72  ction and in par
368b0 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74  ticular must not
368c0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
368d0 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
368e0 49 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  I sqlite3_stmt *
368f0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
36900 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
36910 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
36920 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
36930 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
36940 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
36950 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
36960 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
36970 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
36980 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
36990 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
369a0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
369b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
369c0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
369d0 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
369e0 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
369f0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
36a00 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
36a10 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
36a20 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
36a30 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
36a40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36a50 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
36a60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36a70 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
36a80 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
36a90 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
36aa0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
36ab0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
36ac0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
36ad0 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
36ae0 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
36af0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
36b00 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
36b10 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36b20 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a  rollback_hook().
36b30 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
36b40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36b50 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
36b60 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20  n..** ^The pArg 
36b70 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
36b80 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
36b90 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  e callback..** ^
36ba0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
36bb0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
36bc0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
36bd0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
36be0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
36bf0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
36c00 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
36c10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36c20 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c  commit_hook(D,C,
36c30 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  P) and sqlite3_r
36c40 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43  ollback_hook(D,C
36c50 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ,P) functions.**
36c60 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72   return the P ar
36c70 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
36c80 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66  previous call of
36c90 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
36ca0 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  on.** on the sam
36cb0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
36cc0 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
36cd0 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
36ce0 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63  rst call for eac
36cf0 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e  h function on D.
36d00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69  .**.** The commi
36d10 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68  t and rollback h
36d20 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61 72  ook callbacks ar
36d30 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  e not reentrant.
36d40 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
36d50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36d60 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
36d70 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
36d80 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
36d90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36da0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
36db0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
36dc0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
36dd0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
36de0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
36df0 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
36e00 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
36e10 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
36e20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
36e30 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
36e40 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
36e50 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
36e60 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
36e70 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
36e80 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69 6e 67  ote that running
36e90 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 20 73   any other SQL s
36ea0 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75  tatements, inclu
36eb0 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61 74  ding SELECT stat
36ec0 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65  ements,.** or me
36ed0 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  rely calling [sq
36ee0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
36ef0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
36f00 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f  _step()] will mo
36f10 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
36f20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
36f30 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
36f40 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
36f50 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
36f60 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
36f70 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
36f80 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
36f90 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
36fa0 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
36fb0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
36fc0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
36fd0 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
36fe0 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
36ff0 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
37000 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
37010 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
37020 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
37030 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
37040 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
37050 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
37060 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
37070 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
37080 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
37090 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
370a0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
370b0 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
370c0 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
370d0 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
370e0 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
370f0 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
37100 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
37110 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
37120 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
37130 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
37140 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
37150 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
37160 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
37170 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
37180 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
37190 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
371a0 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
371b0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
371c0 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
371d0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
371e0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
371f0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
37200 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
37210 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
37220 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
37230 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37240 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
37250 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
37260 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
37270 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
37280 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ace..*/.SQLITE_A
37290 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
372a0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
372b0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
372c0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  id*), void*);.SQ
372d0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
372e0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
372f0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
37300 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
37310 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
37320 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
37330 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
37340 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
37350 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
37360 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
37370 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
37380 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
37390 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
373a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
373b0 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65  ction] identifie
373c0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
373d0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  rgument.** to be
373e0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
373f0 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74  r a row is updat
37400 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
37410 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  deleted..** ^Any
37420 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
37430 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
37440 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
37450 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  n.** for the sam
37460 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
37470 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
37480 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  den..**.** ^The 
37490 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
374a0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
374b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
374c0 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a  invoke when a.**
374d0 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
374e0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
374f0 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  eted..** ^The fi
37500 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
37510 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
37520 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
37530 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
37540 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
37550 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68  e_hook()..** ^Th
37560 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
37570 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  k argument is on
37580 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
37590 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
375a0 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  LETE],.** or [SQ
375b0 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65  LITE_UPDATE], de
375c0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
375d0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
375e0 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
375f0 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  k.** to be invok
37600 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  ed..** ^The thir
37610 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
37620 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
37630 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
37640 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ointers to the.*
37650 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  * database and t
37660 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
37670 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
37680 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66  d row..** ^The f
37690 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
376a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
376b0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f  rowid] of the ro
376c0 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61  w..** ^In the ca
376d0 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
376e0 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f   this is the [ro
376f0 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75  wid] after the u
37700 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63  pdate takes plac
37710 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75  e..**.** ^(The u
37720 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
37730 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
37740 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
37750 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
37760 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
37770 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
37780 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29  lite_sequence).)
37790 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ^.**.** ^In the 
377a0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
377b0 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61  tation, the upda
377c0 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f  te hook.** is no
377d0 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64  t invoked when d
377e0 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20  uplication rows 
377f0 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63 61  are deleted beca
37800 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e  use of an.** [ON
37810 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43   CONFLICT | ON C
37820 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d  ONFLICT REPLACE]
37830 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69   clause.  ^Nor i
37840 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  s the update hoo
37850 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65  k.** invoked whe
37860 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
37870 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72  ed using the [tr
37880 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
37890 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63  ion]..** The exc
378a0 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20  eptions defined 
378b0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
378c0 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  h might change i
378d0 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
378e0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
378f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
37900 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74  e hook implement
37910 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
37920 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
37930 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
37940 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
37950 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
37960 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  ked the update h
37970 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ook.  Any action
37980 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
37990 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
379a0 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
379b0 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
379c0 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
379d0 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
379e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
379f0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
37a00 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
37a10 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
37a20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
37a30 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
37a40 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
37a50 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
37a60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37a70 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
37a80 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
37a90 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
37aa0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  aph..**.** ^The 
37ab0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37ac0 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
37ad0 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ion.** returns t
37ae0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
37af0 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
37b00 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  call.** on the s
37b10 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
37b20 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
37b30 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
37b40 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e  first call on D.
37b50 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
37b60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  the [sqlite3_com
37b70 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20  mit_hook()] and 
37b80 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
37b90 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74  k_hook()].** int
37ba0 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 53 51 4c 49  erfaces..*/.SQLI
37bb0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
37bc0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
37bd0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
37be0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
37bf0 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
37c00 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
37c10 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
37c20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
37c30 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
37c40 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
37c50 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
37c60 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
37c70 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
37c80 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
37c90 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
37ca0 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
37cb0 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
37cc0 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
37cd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37ce0 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69  ction | connecti
37cf0 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ons].** to the s
37d00 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68  ame database. Sh
37d10 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
37d20 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
37d30 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20   is true.** and 
37d40 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
37d50 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73  argument is fals
37d60 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68  e.)^.**.** ^Cach
37d70 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61  e sharing is ena
37d80 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65  bled and disable
37d90 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  d for an entire 
37da0 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73  process..** This
37db0 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20   is a change as 
37dc0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
37dd0 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f  n 3.5.0. In prio
37de0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
37df0 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67  Lite,.** sharing
37e00 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
37e10 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
37e20 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
37e30 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
37e40 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d   cache sharing m
37e50 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20  ode set by this 
37e60 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74  interface effect
37e70 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
37e80 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  .** calls to [sq
37e90 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
37ea0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
37eb0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
37ec0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45  _open16()]..** E
37ed0 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65  xisting database
37ee0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e   connections con
37ef0 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68  tinue use the sh
37f00 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68  aring mode.** th
37f10 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74  at was in effect
37f20 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65   at the time the
37f30 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e  y were opened.)^
37f40 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
37f50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
37f60 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
37f70 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e  red cache was en
37f80 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
37f90 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  d.** successfull
37fa0 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f  y.  An [error co
37fb0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
37fc0 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a  otherwise.)^.**.
37fd0 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65  ** ^Shared cache
37fe0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
37ff0 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
38000 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
38010 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
38020 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
38030 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
38040 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
38050 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
38060 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
38070 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
38080 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20  **.** See Also: 
38090 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d   [SQLite Shared-
380a0 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 53  Cache Mode].*/.S
380b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
380c0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
380d0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
380e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
380f0 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
38100 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
38110 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38120 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
38130 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
38140 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
38150 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
38160 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
38170 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
38180 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
38190 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
381a0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
381b0 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
381c0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
381d0 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
381e0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
381f0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
38200 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
38210 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
38220 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
38230 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
38240 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
38250 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
38260 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
38270 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
38280 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
38290 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
382a0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
382b0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
382c0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
382d0 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20  no-op returning 
382e0 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74  zero.** if SQLit
382f0 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65  e is not compile
38300 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45  d with [SQLITE_E
38310 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
38320 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20  AGEMENT]..**.** 
38330 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
38340 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65  e3_db_release_me
38350 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  mory()].*/.SQLIT
38360 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
38370 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
38380 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
38390 50 49 33 52 45 46 3a 20 46 72 65 65 20 4d 65 6d  PI3REF: Free Mem
383a0 6f 72 79 20 55 73 65 64 20 42 79 20 41 20 44 61  ory Used By A Da
383b0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
383c0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
383d0 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f  ite3_db_release_
383e0 6d 65 6d 6f 72 79 28 44 29 20 69 6e 74 65 72 66  memory(D) interf
383f0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
38400 66 72 65 65 20 61 73 20 6d 75 63 68 20 68 65 61  free as much hea
38410 70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70  p.** memory as p
38420 6f 73 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74  ossible from dat
38430 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38440 20 44 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a   D. Unlike the.*
38450 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
38460 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74  se_memory()] int
38470 65 72 66 61 63 65 2c 20 74 68 69 73 20 69 6e 74  erface, this int
38480 65 72 66 61 63 65 20 69 73 20 65 66 66 65 63 74  erface is effect
38490 20 65 76 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68   even.** when th
384a0 65 6e 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  en [SQLITE_ENABL
384b0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
384c0 45 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ENT] compile-tim
384d0 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f  e option is.** o
384e0 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  mitted..**.** Se
384f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
38500 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
38510 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
38520 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
38530 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73  release_memory(s
38540 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
38550 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
38560 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
38570 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  p Size.**.** ^Th
38580 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
38590 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e  eap_limit64() in
385a0 74 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64  terface sets and
385b0 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a  /or queries the.
385c0 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e  ** soft limit on
385d0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
385e0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
385f0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
38600 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e   by SQLite..** ^
38610 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74  SQLite strives t
38620 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f  o keep heap memo
38630 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62  ry utilization b
38640 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65  elow the soft he
38650 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72  ap.** limit by r
38660 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62  educing the numb
38670 65 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64  er of pages held
38680 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63   in the page cac
38690 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65  he.** as heap me
386a0 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72  mory usages appr
386b0 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74  oaches the limit
386c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68  ..** ^The soft h
386d0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f  eap limit is "so
386e0 66 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e  ft" because even
386f0 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73   though SQLite s
38700 74 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a  trives to stay.*
38710 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69  * below the limi
38720 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65  t, it will excee
38730 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68  d the limit rath
38740 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65  er than generate
38750 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  .** an [SQLITE_N
38760 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e  OMEM] error.  In
38770 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
38780 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
38790 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72  t .** is advisor
387a0 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
387b0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
387c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66