System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 35c671cf4b916d42b245d5faaf480fbefaa2cee7:


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 32 22 0a 23 64 65 66 69 6e 65 20 53  .7.12".#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 32 0a 23 64 65  MBER 3007012.#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 35 2d 30 31 20 31 34 3a 32 31 3a 35 37 20  -05-01 14:21:57 
1080: 62 66 61 36 31 65 37 38 31 63 62 34 34 32 62 65  bfa61e781cb442be
1090: 36 34 31 34 38 36 65 37 65 35 35 61 31 35 31 38  641486e7e55a1518
10a0: 65 38 38 38 64 38 33 30 22 0a 0a 2f 2a 0a 2a 2a  e888d830"../*.**
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 69 73 20  _close()].** is 
2490: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20  its destructor. 
24a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
24b0: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
24c0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
24d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
24f0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2500: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2510: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
2520: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
2530: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
2540: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
2550: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
2560: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2570: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
2580: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2590: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
25a0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
25b0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
25c0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
25d0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
25e0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
25f0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
2600: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
2610: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
2620: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
2630: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
2640: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
2650: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
2660: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2670: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2680: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
2690: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
26a0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
26b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
26c0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
26d0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
26e0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
26f0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2700: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2710: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2720: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2730: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
2740: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2750: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
2760: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
2770: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
2780: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
2790: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
27a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
27b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
27c0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
27d0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
27e0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
27f0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
2800: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
2810: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
2820: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2830: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
2840: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2850: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2860: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2870: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
2880: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
2890: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
28a0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
28b0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
28c0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
28d0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
28e0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
28f0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2900: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2910: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2920: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2930: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2940: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2950: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2960: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2970: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2980: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2990: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
29a0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
29b0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
29c0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
29d0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
29e0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
29f0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2a00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2a10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2a20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2a30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2a40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2a50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2a60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2a70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2a80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2a90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2aa0: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
2ab0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ac0: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64  routine is the d
2ad0: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2ae0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2af0: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2b00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2b10: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
2b20: 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  K if the [sqlite
2b30: 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  3] object is.** 
2b40: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
2b50: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
2b60: 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72  ssociated resour
2b70: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2b80: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ted..**.** Appli
2b90: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73 71  cations must [sq
2ba0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2bb0: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
2bc0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bd0: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  nts].** and [sql
2be0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
2bf0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
2c00: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f  OB handles] asso
2c10: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74  ciated with.** t
2c20: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2c30: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74  ect prior to att
2c40: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65  empting to close
2c50: 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49   the object.  ^I
2c60: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f  f.** sqlite3_clo
2c70: 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  se() is called o
2c80: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
2c90: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
2ca0: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
2cb0: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
2cc0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 72  d statements] or
2cd0: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2ce0: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73   then it returns
2cf0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
2d00: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c 69  .**.** ^If [sqli
2d10: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
2d20: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
2d30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
2d40: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
2d50: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
2d60: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2d70: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2d80: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2d90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2da0: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2db0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2dc0: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2dd0: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2de0: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2df0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2e00: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2e10: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
2e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2e30: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
2e40: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
2e50: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
2e60: 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68 20  e3_close() with 
2e70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
2e80: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a 2a  rgument is a .**
2e90: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2ea0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2eb0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2ec0: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2ed0: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2ee0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2ef0: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2f00: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2f10: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
2f20: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
2f30: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
2f40: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
2f50: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
2f60: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
2f70: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2f80: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2f90: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2fa0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2fb0: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2fc0: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2fe0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
2ff0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
3000: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
3010: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
3020: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
3030: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3040: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3050: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3060: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3070: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3080: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3090: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
30a0: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
30b0: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
30c0: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
30d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
30e0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
30f0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
3100: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
3110: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
3120: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3130: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3140: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3150: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3160: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3180: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3190: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
31a0: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
31b0: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
31c0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
31d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
31e0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
31f0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
3200: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
3210: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
3220: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
3230: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3240: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3250: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3260: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3270: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3280: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3290: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
32a0: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
32b0: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
32c0: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
32d0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
32e0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
32f0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
3300: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
3310: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
3320: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
3330: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3340: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3350: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3360: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3370: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3380: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3390: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
33a0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
33b0: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
33c0: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
33d0: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
33e0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
33f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3400: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
3410: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
3420: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
3430: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3440: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3450: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3460: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3470: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3480: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3490: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
34a0: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
34b0: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
34c0: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
34d0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
34e0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
34f0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3500: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3510: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3520: 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  of.** of sqlite3
3530: 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68  _exec() after th
3540: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
3550: 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e  string is no lon
3560: 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e  ger needed..** ^
3570: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  If the 5th param
3580: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3590: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55  exec() is not NU
35a0: 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73  LL and no errors
35b0: 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20  .** occur, then 
35c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73  sqlite3_exec() s
35d0: 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ets the pointer 
35e0: 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d  in its 5th param
35f0: 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20  eter to.** NULL 
3600: 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
3610: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73  ..**.** ^If an s
3620: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3630: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
3640: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c  on-zero, the sql
3650: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72  ite3_exec().** r
3660: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53  outine returns S
3670: 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68  QLITE_ABORT with
3680: 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  out invoking the
3690: 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20   callback again 
36a0: 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72  and.** without r
36b0: 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65  unning any subse
36c0: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  quent SQL statem
36d0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
36e0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   2nd argument to
36f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3700: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  c() callback fun
3710: 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20  ction is the.** 
3720: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
3730: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e  s in the result.
3740: 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d    ^The 3rd argum
3750: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3760: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c  e3_exec().** cal
3770: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3780: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3790: 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65   strings obtaine
37a0: 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20  d as if from.** 
37b0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37c0: 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72  text()], one for
37d0: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e   each column.  ^
37e0: 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66  If an element of
37f0: 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77   a.** result row
3800: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
3810: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
3820: 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66  string pointer f
3830: 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  or the.** sqlite
3840: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3850: 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  k is a NULL poin
3860: 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61  ter.  ^The 4th a
3870: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
3880: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3890: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
38a0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
38b0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65  s to strings whe
38c0: 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79  re each.** entry
38d0: 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20   represents the 
38e0: 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f  name of correspo
38f0: 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c  nding result col
3900: 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a  umn as obtained.
3910: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
3920: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e  _column_name()].
3930: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32  .**.** ^If the 2
3940: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3950: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3960: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3970: 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  , a pointer.** t
3980: 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
3990: 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  g, or a pointer 
39a0: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e  that contains on
39b0: 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e  ly whitespace an
39c0: 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d  d/or .** SQL com
39d0: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
39e0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
39f0: 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20  e evaluated and 
3a00: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
3a10: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
3a20: 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f  **.** Restrictio
3a30: 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ns:.**.** <ul>.*
3a40: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
3a50: 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75  cation must insu
3a60: 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20  re that the 1st 
3a70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a80: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20  ite3_exec().**  
3a90: 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61      is a valid a
3aa0: 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  nd open [databas
3ab0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
3ac0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
3ad0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
3ae0: 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20  close [database 
3af0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
3b00: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
3b10: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3b20: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b30: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3b40: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3b50: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
3b60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3b70: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
3b80: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
3b90: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
3ba0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
3bb0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
3bc0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3bd0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3be0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3bf0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
3c00: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
3c10: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
3c20: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c40: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
3c50: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
3c60: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
3c90: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
3ca0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
3cb0: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3cc0: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
3cd0: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
3ce0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
3cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d10: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
3d20: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
3d30: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
3d40: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
3d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d60: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
3d70: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
3d80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3d90: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
3da0: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
3db0: 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65  E_OK {error code
3dc0: 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  } {error codes}.
3dd0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
3de0: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75  sult code} {resu
3df0: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
3e00: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
3e10: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
3e20: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
3e30: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
3e40: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
3e50: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
3e60: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
3e70: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3e80: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3e90: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3ea0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3eb0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3ec0: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3ed0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3ee0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3ef0: 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  des],.** [sqlite
3f00: 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
3f10: 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f  ct()] [SQLITE_RO
3f20: 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20  LLBACK | result 
3f30: 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69  codes]..*/.#defi
3f40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
3f50: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
3f60: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
3f70: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
3f80: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
3f90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3fa0: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
3fb0: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
3fc0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
3fd0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
3fe0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
3ff0: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4000: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
4010: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
4020: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
4030: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
4040: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
4050: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4060: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
4070: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
4080: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
4090: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
40a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
40b0: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
40c0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
40d0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
40e0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
40f0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4100: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
4110: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4120: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
4130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
4140: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
4150: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
4160: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4170: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
4180: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
4190: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
41a0: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
41b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
41c0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
41d0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
41e0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
41f0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4210: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
4220: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
4230: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
4240: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
4250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
4260: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
4270: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
4280: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
4290: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
42a0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
42b0: 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f     12   /* Unkno
42c0: 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c  wn opcode in sql
42d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
42e0: 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  l() */.#define S
42f0: 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20  QLITE_FULL      
4300: 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74    13   /* Insert
4310: 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75  ion failed becau
4320: 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66  se database is f
4330: 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ull */.#define S
4340: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20  QLITE_CANTOPEN  
4350: 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65    14   /* Unable
4360: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
4370: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f  efine SQLITE_PRO
4390: 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a  TOCOL    15   /*
43a0: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
43b0: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
43c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
43d0: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
43e0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
43f0: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
4400: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
4410: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
4420: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
4430: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
4440: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
4450: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
4460: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
4470: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
44a0: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
44b0: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
44c0: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
44e0: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
44f0: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
4500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4510: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
4520: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
4530: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
4560: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
4570: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
4580: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
4590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
45a0: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
45b0: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
45c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
45d0: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
45e0: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
45f0: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
4600: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4620: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
4630: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
4640: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
4650: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4670: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
4680: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
4690: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
46a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
46c0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
46d0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
46e0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
46f0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4700: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4710: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4720: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4730: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4740: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4750: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4760: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4770: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4780: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4790: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72  DS: {extended er
47a0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ror code} {exten
47b0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d  ded error codes}
47c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
47d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
47e0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72  ode} {extended r
47f0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
4800: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4810: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4820: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4830: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4840: 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a  of 26 integer.**
4850: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
4860: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
4870: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
4880: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
4890: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
48a0: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
48b0: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
48c0: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
48d0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
48e0: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
48f0: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
4900: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
4910: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
4920: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
4930: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
4940: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
4950: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
4960: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
4970: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
4980: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
4990: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
49a0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
49b0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
49c0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
49d0: 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74   errors. The ext
49e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49f0: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f  es are enabled o
4a00: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e  r disabled.** on
4a10: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20   a per database 
4a20: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
4a30: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
4a40: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
4a50: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20  result_codes()] 
4a60: 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  API..**.** Some 
4a70: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
4a80: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a90: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
4aa0: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d  d here..** One m
4ab0: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75  ay expect the nu
4ac0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64  mber of extended
4ad0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69   result codes wi
4ae0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20  ll be expand.** 
4af0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
4b00: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
4b10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4b20: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
4b30: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
4b40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
4b50: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
4b60: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4b70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
4b80: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
4b90: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
4ba0: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
4bb0: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
4bc0: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69  y zero..*/.#defi
4bd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4be0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4bf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c00: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4c10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4c20: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4c30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4c40: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4c50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4c60: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4c70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c80: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4c90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ca0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
4cb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4cc0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
4cd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
4ce0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
4cf0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
4d00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4d10: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
4d20: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
4d30: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
4d40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4d50: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
4d60: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4d70: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
4dc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4dd0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
4de0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4df0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
4e00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e10: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
4e20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4e30: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
4e40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e50: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
4e60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4e70: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
4e80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e90: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
4ea0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4eb0: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
4ec0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4ed0: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
4ee0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4ef0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
4f00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f10: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
4f20: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
4f30: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
4f40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f50: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
4f60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f70: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
4f80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f90: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
4fa0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4fb0: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
4fc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4fd0: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
4fe0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4ff0: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5000: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5010: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5020: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5030: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5040: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5050: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
5060: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5070: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
5080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5090: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
50a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50b0: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
50c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50d0: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
50e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50f0: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5100: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5110: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5120: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5130: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5140: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5150: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5160: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5170: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5190: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51b0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
51e0: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
51f0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5200: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5210: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5220: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5230: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5240: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5250: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5260: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
5270: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5280: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5290: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
52a0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
52b0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
52c0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
52d0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f  ne SQLITE_ABORT_
52e0: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20  ROLLBACK        
52f0: 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20    (SQLITE_ABORT 
5300: 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (2<<8))../*.**
5310: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
5320: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
5330: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
5340: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5350: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5360: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5370: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5390: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
53a0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
53b0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
53c0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
53d0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
53e0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
53f0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5400: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
5410: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
5420: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5430: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5440: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5450: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5460: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
5470: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5480: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5490: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
54a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
54b0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
54c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
54d0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
54e0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
54f0: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5500: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
5510: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5520: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5530: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
5540: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
5550: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5560: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
5570: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
5580: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
5590: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
55a0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
55b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
55c0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
55d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
55e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
55f0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
5600: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5610: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
5620: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5630: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
5640: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5650: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
5660: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5670: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5680: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5690: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
56a0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
56b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
56c0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
56d0: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
56e0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
56f0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5700: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5710: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
5720: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5730: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
5740: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
5750: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
5760: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5770: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
5780: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
5790: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
57a0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
57b0: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
57c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
57d0: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
57e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
57f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5800: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
5810: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
5820: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
5830: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5840: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5850: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
5860: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
5870: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
5880: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5890: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
58a0: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
58b0: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
58c0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
58d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
58e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
58f0: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
5900: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
5910: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
5920: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
5930: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
5940: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
5950: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
5960: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
5970: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
5980: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
5990: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
59a0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
59b0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
59c0: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
59d0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
59e0: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
59f0: 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65  tor of the these
5a00: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
5a10: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
5a20: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
5a30: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
5a40: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
5a50: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
5a60: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
5a70: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
5a80: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
5a90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
5aa0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
5ab0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
5ac0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
5ad0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
5ae0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
5af0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
5b00: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
5b10: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
5b20: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
5b30: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
5b40: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
5b50: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
5b60: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
5b70: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
5b80: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
5b90: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
5ba0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5bb0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
5bc0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
5bd0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
5be0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
5bf0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
5c00: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
5c10: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
5c20: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
5c30: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
5c40: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
5c50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
5c60: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
5c70: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
5c80: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
5c90: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
5ca0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
5cb0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
5cc0: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
5cd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
5ce0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
5cf0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5d00: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
5d10: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
5d20: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
5d30: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
5d40: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
5d50: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
5d60: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
5d70: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
5d80: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
5d90: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
5da0: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
5db0: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
5dc0: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
5dd0: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
5de0: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   be unchanged..*
5df0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
5e10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5e20: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
5e30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e40: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
5e50: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
5e60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5e70: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
5e80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5e90: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5eb0: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
5ec0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
5ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5ee0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
5ef0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5f00: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
5f10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5f20: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
5f30: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
5f40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5f50: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
5f60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5f70: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
5f80: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
5f90: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
5fa0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
5fb0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5fc0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
5fd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5fe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ff0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6000: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
6010: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6020: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6030: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6040: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
6050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6060: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6070: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
6080: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
6090: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
60a0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
60b0: 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a    0x00001000../*
60c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
60d0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
60e0: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
60f0: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6100: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6110: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6120: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6130: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6140: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6150: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6160: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6170: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6180: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6190: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
61a0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
61b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
61c0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
61d0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
61e0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
61f0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6200: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6210: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6220: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6230: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6240: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6250: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6260: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6270: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6280: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6290: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
62a0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
62b0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
62c0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
62d0: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
62e0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
62f0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6300: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6310: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6320: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6330: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6340: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6350: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6360: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6370: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6380: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6390: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
63a0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
63b0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
63c0: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
63d0: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
63e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
63f0: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6400: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6410: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6420: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6430: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6440: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6450: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6460: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6470: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6480: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6490: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
64a0: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
64b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
64c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
64d0: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
64e0: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
64f0: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
6500: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
6510: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
6520: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
6530: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
6540: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
6550: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
6560: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
6570: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
6580: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
6590: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
65a0: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
65b0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
65c0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
65d0: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
65e0: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
65f0: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
6600: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
6610: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
6620: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
6630: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
6640: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
6650: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
6660: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
6670: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
6680: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6690: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
66a0: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
66b0: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
66c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
66d0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
66e0: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
66f0: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
6700: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
6710: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
6720: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
6730: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
6740: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
6750: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
6760: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6770: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
6780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6790: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
67a0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
67b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
67c0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
67d0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
67e0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
67f0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
6800: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
6810: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6820: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
6830: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
6840: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
6850: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
6860: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
6870: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
6880: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
6890: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
68a0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
68b0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
68c0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
68d0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
68e0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
68f0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
6900: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
6910: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
6920: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6930: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
6940: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
6950: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
6960: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
6970: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
6980: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
6990: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
69a0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
69b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
69c0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
69d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
69e0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
69f0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
6a00: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
6a10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6a20: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
6a30: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
6a40: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
6a50: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
6a60: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
6a70: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6a80: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
6a90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
6aa0: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
6ab0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
6ac0: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
6ad0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
6ae0: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
6af0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
6b00: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
6b10: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
6b20: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
6b30: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
6b40: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
6b50: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
6b60: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
6b70: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
6b80: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
6b90: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
6ba0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
6bb0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6bc0: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
6bd0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
6be0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
6bf0: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
6c00: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
6c10: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
6c20: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
6c30: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
6c40: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
6c50: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6c60: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
6c70: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
6c80: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
6c90: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
6ca0: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
6cb0: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
6cc0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
6cd0: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
6ce0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
6cf0: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
6d00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
6d10: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
6d20: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
6d30: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
6d40: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6d50: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6d60: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6d70: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6d80: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6d90: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6da0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6db0: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6dc0: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6dd0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6de0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
6df0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
6e00: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
6e10: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
6e20: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
6e30: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
6e40: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6e50: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6e60: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6e70: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6e80: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6e90: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6ea0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6eb0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6ec0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6ed0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6ee0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
6ef0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
6f00: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
6f10: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
6f20: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
6f30: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6f40: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6f50: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6f60: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6f70: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6f80: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6f90: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6fa0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6fb0: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6fc0: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6fd0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6fe0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
6ff0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7000: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7010: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7020: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7030: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7040: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7050: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7060: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7070: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7080: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7090: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
70a0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
70b0: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
70c0: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
70d0: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
70e0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
70f0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7100: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7110: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7120: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7130: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7140: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7150: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7160: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7170: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7180: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7190: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
71a0: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
71b0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
71c0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
71d0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
71e0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
71f0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7200: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7210: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7220: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7230: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7240: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7250: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7260: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7270: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7280: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7290: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
72a0: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
72b0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
72c0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
72d0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
72e0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
72f0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7300: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7310: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7320: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7330: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7340: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
7350: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
7360: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7370: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7380: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7390: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
73a0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
73b0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
73c0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
73d0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
73e0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
73f0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7400: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7410: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7420: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7430: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7440: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7450: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7460: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7470: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7480: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7490: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
74a0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
74b0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
74c0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
74d0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
74e0: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
74f0: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7500: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7510: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7520: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7530: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7540: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7550: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7560: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7570: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7580: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7590: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
75a0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
75b0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
75c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
75d0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
75e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
75f0: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
7600: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7610: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
7620: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7630: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
7640: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7650: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
7660: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7670: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
7680: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7690: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
76a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
76b0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
76c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
76d0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
76e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
76f0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
7700: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7710: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7720: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
7730: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7740: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
7750: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
7760: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
7770: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
7780: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7790: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
77a0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
77b0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
77c0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
77d0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
77e0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
77f0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7800: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7810: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7820: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7830: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7840: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7850: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
7860: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
7870: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
7880: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
7890: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
78a0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
78b0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
78c0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
78d0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
78e0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
78f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7900: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7910: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7920: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7930: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7940: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7950: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
7960: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
7970: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
7980: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
7990: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
79a0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
79b0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
79c0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
79d0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
79e0: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
79f0: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7a00: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7a10: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7a20: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7a30: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7a40: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7a50: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
7a60: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
7a70: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
7a80: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7a90: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7aa0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
7ab0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7ac0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7ad0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7ae0: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7af0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7b00: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7b10: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7b20: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7b30: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7b40: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7b50: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
7b60: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
7b70: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
7b80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
7b90: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
7ba0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
7bb0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7bc0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7bd0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7be0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7bf0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7c00: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7c10: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7c20: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7c30: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7c40: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7c50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
7c60: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
7c70: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
7c80: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
7c90: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
7ca0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
7cb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7cc0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7cd0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7ce0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7cf0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7d00: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7d10: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7d20: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7d30: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7d40: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7d50: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
7d60: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
7d70: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
7d80: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7d90: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
7da0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
7db0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7dc0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7dd0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7de0: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7df0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7e00: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7e10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7e20: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7e30: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7e40: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7e50: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
7e60: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
7e70: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
7e80: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
7e90: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
7ea0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
7eb0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7ec0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7ed0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7ee0: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7ef0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7f00: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7f10: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7f20: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7f30: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7f40: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7f50: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
7f60: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
7f70: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
7f80: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
7f90: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
7fa0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
7fb0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7fc0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7fd0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7fe0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7ff0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8000: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8010: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8020: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8030: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8040: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8050: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8060: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8070: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8080: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8090: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
80a0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
80b0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
80c0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
80d0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
80e0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
80f0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8100: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
8110: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
8120: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
8130: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
8140: 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  ned..** <ul>.** 
8150: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8160: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a  TL_SIZE_HINT]].*
8170: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8180: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
8190: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
81a0: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
81b0: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
81c0: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
81d0: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
81e0: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
81f0: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
8200: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
8210: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
8220: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
8230: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
8240: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
8250: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
8260: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
8270: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
8280: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
8290: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
82a0: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
82b0: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
82c0: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
82d0: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
82e0: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
82f0: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ster..**.** <li>
8300: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
8310: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  HUNK_SIZE]].** T
8320: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8330: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
8340: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
8350: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
8360: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
8370: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
8380: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
8390: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
83a0: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
83b0: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
83c0: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
83d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
83e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
83f0: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
8400: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
8410: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
8420: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
8430: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
8440: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
8450: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
8460: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
8470: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
8480: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
8490: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
84a0: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
84b0: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
84c0: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
84d0: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
84e0: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
84f0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
8500: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8510: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68  _POINTER]].** Th
8520: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8530: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
8540: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8550: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
8560: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
8570: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
8580: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
8590: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
85a0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
85b0: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
85c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
85d0: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
85e0: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
85f0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
8600: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
8610: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8620: 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20  NC_OMITTED]].** 
8630: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  ^(The [SQLITE_FC
8640: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
8650: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
8660: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
8670: 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e   by.** SQLite an
8680: 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46  d sent to all VF
8690: 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  Ses in place of 
86a0: 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53  a call to the xS
86b0: 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68  ync method.** wh
86c0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
86d0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b  connection has [
86e0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
86f0: 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29  us] set to OFF.)
8700: 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61  ^.** Some specia
8710: 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64  lized VFSes need
8720: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20   this signal in 
8730: 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65  order to operate
8740: 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68   correctly.** wh
8750: 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  en [PRAGMA synch
8760: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
8770: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
8780: 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73   is set, but mos
8790: 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e  t .** VFSes do n
87a0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
87b0: 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73  nal and should s
87c0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
87d0: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41  his opcode..** A
87e0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
87f0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
8800: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8810: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a  l()] with this.*
8820: 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  * opcode as doin
8830: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
8840: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
8850: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
8860: 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20  d VFSes.** that 
8870: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
8880: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8890: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
88a0: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
88b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
88c0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
88d0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
88e0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
88f0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
8900: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
8910: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
8920: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
8930: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
8940: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
8950: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
8960: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
8970: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
8980: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
8990: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
89a0: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
89b0: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
89c0: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
89d0: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
89e0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
89f0: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
8a00: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
8a10: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
8a20: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
8a30: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
8a40: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
8a50: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
8a60: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
8a70: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
8a80: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
8a90: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
8aa0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
8ab0: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
8ac0: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
8ad0: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
8ae0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
8af0: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
8b00: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
8b10: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
8b20: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
8b30: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
8b40: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
8b50: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
8b60: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
8b70: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
8b80: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
8b90: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
8ba0: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
8bb0: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
8bc0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
8bd0: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
8be0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
8bf0: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
8c00: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
8c10: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
8c20: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
8c30: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
8c40: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
8c50: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
8c60: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
8c70: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
8c80: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
8c90: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
8ca0: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
8cb0: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
8cc0: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
8cd0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
8ce0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
8cf0: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
8d00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8d10: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
8d20: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8d30: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
8d40: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
8d50: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 48 65 61  WAL | Write AHea
8d60: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
8d70: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
8d80: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
8d90: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
8da0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
8db0: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
8dc0: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
8dd0: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
8de0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
8df0: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
8e00: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
8e10: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
8e20: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
8e30: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
8e40: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
8e50: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
8e60: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
8e70: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
8e80: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
8e90: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
8ea0: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
8eb0: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
8ec0: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
8ed0: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
8ee0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
8ef0: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
8f00: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
8f10: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
8f20: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
8f30: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
8f40: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
8f50: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
8f60: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
8f70: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
8f80: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
8f90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
8fa0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
8fb0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
8fc0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
8fd0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
8fe0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
8ff0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
9000: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9010: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
9020: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
9030: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
9040: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
9050: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
9060: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
9070: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
9080: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
9090: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
90a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
90b0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
90c0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
90d0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
90e0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
90f0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9100: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
9110: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
9120: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
9130: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
9140: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
9150: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
9160: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
9170: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
9180: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
9190: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
91a0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
91b0: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
91c0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
91d0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
91e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
91f0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9200: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9210: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9220: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9230: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9240: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
9250: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
9260: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
9270: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
9280: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
9290: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
92a0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
92b0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
92c0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
92d0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
92e0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
92f0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
9300: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9310: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
9320: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
9330: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
9340: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
9350: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
9360: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
9370: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
9380: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
9390: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
93a0: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
93b0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
93c0: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
93d0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
93e0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
93f0: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
9400: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
9410: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9420: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
9430: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9440: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
9450: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
9460: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
9470: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
9480: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
9490: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
94a0: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
94b0: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
94c0: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
94d0: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
94e0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
94f0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
9500: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
9510: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
9520: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
9530: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
9540: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
9550: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
9560: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
9570: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9580: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
9590: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
95a0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
95b0: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
95c0: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
95d0: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
95e0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
95f0: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
9600: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
9610: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
9620: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
9630: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
9640: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
9650: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
9660: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
9670: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
9680: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
9690: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
96a0: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
96b0: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
96c0: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
96d0: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
96e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
96f0: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e  TL_PRAGMA]].** ^
9700: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47  Whenever a [PRAG
9710: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  MA] statement is
9720: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c   parsed, an [SQL
9730: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
9740: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  ] .** file contr
9750: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68  ol is sent to th
9760: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e open [sqlite3_
9770: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72  file] object cor
9780: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f  responding.** to
9790: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
97a0: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  le to which the 
97b0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
97c0: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72   refers. ^The ar
97d0: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
97e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
97f0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
9800: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20  rol is an array 
9810: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  of.** pointers t
9820: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a  o strings (char*
9830: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  *) in which the 
9840: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f  second element o
9850: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69  f the array.** i
9860: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
9870: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65  e pragma and the
9880: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69   third element i
9890: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
98a0: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20  o the.** pragma 
98b0: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70  or NULL if the p
98c0: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67  ragma has no arg
98d0: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e  ument.  ^The han
98e0: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b  dler for an.** [
98f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9900: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
9910: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79  l can optionally
9920: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20   make the first 
9930: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  element.** of th
9940: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e  e char** argumen
9950: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  t point to a str
9960: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
9970: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
9980: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20  tf()].** or the 
9990: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74  equivalent and t
99a0: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  hat string will 
99b0: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c  become the resul
99c0: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  t of the pragma 
99d0: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  or.** the error 
99e0: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70  message if the p
99f0: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66  ragma fails. ^If
9a00: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
9a10: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
9a20: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
9a30: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ns [SQLITE_NOTFO
9a40: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61  UND], then norma
9a50: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70  l .** [PRAGMA] p
9a60: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e  rocessing contin
9a70: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ues.  ^If the [S
9a80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
9a90: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
9aa0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
9ab0: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68  ITE_OK], then th
9ac0: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73  e parser assumes
9ad0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53   that the.** VFS
9ae0: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65   has handled the
9af0: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61   PRAGMA itself a
9b00: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65  nd the parser ge
9b10: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a  nerates a no-op.
9b20: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
9b30: 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ement.  ^If the 
9b40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9b50: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
9b60: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
9b70: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
9b80: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
9b90: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
9ba0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
9bb0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
9bc0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
9bd0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
9be0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
9bf0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
9c00: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
9c10: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
9c20: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
9c30: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
9c40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
9c50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
9c60: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
9c70: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
9c80: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
9c90: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
9ca0: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
9cb0: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
9cc0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
9cd0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
9ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
9cf0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
9d00: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
9d10: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
9d20: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
9d30: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
9d40: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
9d50: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
9d60: 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
9d70: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
9d80: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
9d90: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
9da0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
9db0: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
9dc0: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
9dd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
9de0: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
9df0: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
9e00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9e10: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
9e20: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
9e30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9e40: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
9e50: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
9e60: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9e70: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
9e80: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
9e90: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9ea0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
9eb0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
9ec0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
9ed0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
9ee0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
9ef0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
9f00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
9f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9f20: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9f30: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
9f40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
9f50: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
9f60: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 0a              14..
9f70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9f80: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
9f90: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
9fa0: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
9fb0: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
9fc0: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
9fd0: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
9fe0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
9ff0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
a000: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
a010: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
a020: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
a030: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
a040: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
a050: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
a060: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
a070: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
a080: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
a090: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
a0a0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
a0b0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
a0c0: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
a0d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
a0e0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
a0f0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
a100: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
a110: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
a120: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
a130: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
a140: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
a150: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
a160: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
a170: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
a180: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
a190: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
a1a0: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
a1b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
a1c0: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
a1d0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
a1e0: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
a1f0: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
a200: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
a210: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
a220: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
a230: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
a240: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
a250: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
a260: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
a270: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
a280: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
a290: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
a2a0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
a2b0: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
a2c0: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
a2d0: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
a2e0: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
a2f0: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
a300: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
a310: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
a320: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
a330: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
a340: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
a350: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
a360: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
a370: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
a380: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
a390: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
a3a0: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
a3b0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
a3c0: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
a3d0: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
a3e0: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
a3f0: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
a400: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
a410: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
a420: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
a430: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
a440: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
a450: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
a460: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
a470: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
a480: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
a490: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
a4a0: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
a4b0: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
a4c0: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
a4d0: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
a4e0: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
a4f0: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
a500: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
a510: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
a520: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
a530: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
a540: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
a550: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
a560: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
a570: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a580: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
a590: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
a5a0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
a5b0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
a5c0: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
a5d0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
a5e0: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
a5f0: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
a600: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
a610: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
a620: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
a630: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
a640: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
a650: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
a660: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
a670: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
a680: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
a690: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
a6a0: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
a6b0: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
a6c0: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
a6d0: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
a6e0: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
a6f0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
a700: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
a710: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
a720: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
a730: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
a740: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
a750: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
a760: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
a770: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
a780: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
a790: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
a7a0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
a7b0: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
a7c0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
a7d0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
a7e0: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
a7f0: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
a800: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
a810: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
a820: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
a830: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
a840: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
a850: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
a860: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
a870: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
a880: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
a890: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
a8a0: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
a8b0: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
a8c0: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
a8d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
a8e0: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
a8f0: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
a900: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
a910: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
a920: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
a930: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
a940: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
a950: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
a960: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
a970: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
a980: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
a990: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
a9a0: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
a9b0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
a9c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
a9d0: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
a9e0: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
a9f0: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
aa00: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
aa10: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
aa20: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
aa30: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
aa40: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
aa50: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
aa60: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
aa70: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
aa80: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
aa90: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
aaa0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
aab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
aac0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
aad0: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
aae0: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
aaf0: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
ab00: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
ab10: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
ab20: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
ab30: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
ab40: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
ab50: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
ab60: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
ab70: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
ab80: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
ab90: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
aba0: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
abb0: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
abc0: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
abd0: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
abe0: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
abf0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
ac00: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
ac10: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
ac20: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
ac30: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
ac40: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
ac50: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
ac60: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
ac70: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
ac80: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
ac90: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
aca0: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
acb0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
acc0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
acd0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ace0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
acf0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ad00: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
ad10: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
ad20: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
ad30: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
ad40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
ad50: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
ad60: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ad70: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
ad80: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ad90: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
ada0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
adb0: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
adc0: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
add0: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
ade0: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
adf0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
ae00: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
ae10: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
ae20: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
ae30: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
ae40: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
ae50: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
ae60: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
ae70: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
ae80: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
ae90: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
aea0: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
aeb0: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
aec0: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
aed0: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
aee0: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
aef0: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
af00: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
af10: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
af20: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
af30: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
af40: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
af50: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
af60: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
af70: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
af80: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
af90: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
afa0: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
afb0: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
afc0: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
afd0: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
afe0: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
aff0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
b000: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
b010: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
b020: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
b030: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
b040: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
b050: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
b060: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
b070: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
b080: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
b090: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
b0a0: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
b0b0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
b0c0: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
b0d0: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
b0e0: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
b0f0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
b100: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
b110: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
b120: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
b130: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
b140: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
b150: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
b160: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
b170: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
b180: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
b190: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
b1a0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
b1b0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
b1c0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
b1d0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
b1e0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
b1f0: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
b200: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
b210: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
b220: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
b230: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
b240: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
b250: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
b260: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
b270: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
b280: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
b290: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
b2a0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
b2b0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
b2c0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
b2d0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
b2e0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
b2f0: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
b300: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
b310: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
b320: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
b330: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
b340: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
b350: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
b360: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
b370: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
b380: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
b390: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
b3a0: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
b3b0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
b3c0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
b3d0: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
b3e0: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
b3f0: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
b400: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
b410: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
b420: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
b430: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
b440: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
b450: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
b460: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
b470: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
b480: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
b490: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
b4a0: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
b4b0: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
b4c0: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
b4d0: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
b4e0: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
b4f0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
b500: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
b510: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
b520: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
b530: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
b540: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
b550: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
b560: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
b570: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
b580: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
b590: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
b5a0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
b5b0: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
b5c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
b5d0: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
b5e0: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
b5f0: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
b600: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
b610: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
b620: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
b630: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
b640: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
b650: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
b660: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
b670: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
b680: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
b690: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
b6a0: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
b6b0: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
b6c0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
b6d0: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
b6e0: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
b6f0: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
b700: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
b710: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
b720: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
b730: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
b740: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
b750: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
b760: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
b770: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
b780: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
b790: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
b7a0: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
b7b0: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
b7c0: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
b7d0: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
b7e0: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
b7f0: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
b800: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
b810: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
b820: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
b830: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
b840: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
b850: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
b860: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
b870: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
b880: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
b890: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
b8a0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
b8b0: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
b8c0: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
b8d0: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
b8e0: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
b8f0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
b900: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
b910: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
b920: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
b930: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
b940: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
b950: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
b960: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
b970: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
b980: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
b990: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
b9a0: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
b9b0: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
b9c0: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
b9d0: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
b9e0: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
b9f0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
ba00: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
ba10: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
ba20: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
ba30: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
ba40: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
ba50: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
ba60: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
ba70: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
ba80: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
ba90: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
baa0: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
bab0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
bac0: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
bad0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
bae0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
baf0: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
bb00: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
bb10: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
bb20: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
bb30: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
bb40: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
bb50: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
bb60: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
bb70: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
bb80: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
bb90: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
bba0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
bbb0: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
bbc0: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
bbd0: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
bbe0: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
bbf0: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
bc00: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
bc10: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
bc20: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
bc30: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
bc40: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
bc50: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
bc60: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
bc70: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
bc80: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
bc90: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
bca0: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
bcb0: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
bcc0: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
bcd0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
bce0: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
bcf0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
bd00: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
bd10: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
bd20: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
bd30: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
bd40: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
bd50: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
bd60: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
bd70: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
bd80: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
bd90: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
bda0: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
bdb0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
bdc0: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
bdd0: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
bde0: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
bdf0: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
be00: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
be10: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
be20: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
be30: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
be40: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
be50: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
be60: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
be70: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
be80: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
be90: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
bea0: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
beb0: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
bec0: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
bed0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
bee0: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
bef0: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
bf00: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
bf10: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
bf20: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
bf30: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
bf40: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
bf50: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
bf60: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
bf70: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
bf80: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
bf90: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
bfa0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
bfb0: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
bfc0: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
bfd0: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
bfe0: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
bff0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
c000: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
c010: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
c020: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
c030: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
c040: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
c050: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
c060: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
c070: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
c080: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
c090: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
c0a0: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
c0b0: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
c0c0: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
c0d0: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
c0e0: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
c0f0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
c100: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
c110: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
c120: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
c130: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
c140: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
c150: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
c160: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
c170: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
c180: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
c190: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
c1a0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
c1b0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
c1c0: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
c1d0: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
c1e0: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
c1f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
c200: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
c210: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
c220: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
c230: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
c240: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
c250: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
c260: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
c270: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
c280: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
c290: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
c2a0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
c2b0: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
c2c0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
c2d0: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
c2e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c2f0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
c300: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
c310: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
c320: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
c330: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
c340: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
c350: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
c360: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
c370: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
c380: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
c390: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
c3a0: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
c3b0: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
c3c0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
c3d0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
c3e0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
c3f0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
c400: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
c410: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
c420: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
c430: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
c440: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
c450: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
c460: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
c470: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
c480: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
c490: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
c4a0: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
c4b0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
c4c0: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
c4d0: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
c4e0: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
c4f0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
c500: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
c510: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
c520: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
c530: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
c540: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
c550: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
c560: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
c570: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
c580: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
c590: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
c5a0: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
c5b0: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
c5c0: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
c5d0: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
c5e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c5f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c600: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
c610: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
c620: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
c630: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
c640: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c650: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
c660: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
c670: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
c680: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c690: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
c6a0: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
c6b0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
c6c0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
c6d0: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
c6e0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
c6f0: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
c700: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
c710: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
c720: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
c730: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
c740: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
c750: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
c760: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
c770: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
c780: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
c790: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
c7a0: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
c7b0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
c7c0: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
c7d0: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
c7e0: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
c7f0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
c800: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
c810: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
c820: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
c830: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
c840: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
c850: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
c860: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
c870: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
c880: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
c890: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
c8a0: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
c8b0: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
c8c0: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
c8d0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
c8e0: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
c8f0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
c900: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
c910: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
c920: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
c930: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
c940: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
c950: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
c960: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
c970: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
c980: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
c990: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
c9a0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
c9b0: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
c9c0: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
c9d0: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
c9e0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
c9f0: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
ca00: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
ca10: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
ca20: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
ca30: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
ca40: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
ca50: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
ca60: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
ca70: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
ca80: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
ca90: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
caa0: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
cab0: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
cac0: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
cad0: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
cae0: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
caf0: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
cb00: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
cb10: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
cb20: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
cb30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
cb40: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
cb50: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
cb60: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
cb70: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
cb80: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
cb90: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
cba0: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
cbb0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
cbc0: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
cbd0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
cbe0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
cbf0: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
cc00: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
cc10: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
cc20: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
cc30: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
cc40: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
cc50: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
cc60: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
cc70: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
cc80: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
cc90: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
cca0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
ccb0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
ccc0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
ccd0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
cce0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
ccf0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
cd00: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
cd10: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
cd20: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
cd30: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
cd40: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
cd50: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
cd60: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
cd70: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
cd80: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
cd90: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
cda0: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
cdb0: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
cdc0: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
cdd0: 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65  was given no the
cde0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
cdf0: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
ce00: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
ce10: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
ce20: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
ce30: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
ce40: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
ce50: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
ce60: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
ce70: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
ce80: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
ce90: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
cea0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
ceb0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
cec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
ced0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
cee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
cef0: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
cf00: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
cf10: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
cf20: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
cf30: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
cf40: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
cf50: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
cf60: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
cf70: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
cf80: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
cf90: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
cfa0: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
cfb0: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
cfc0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
cfd0: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
cfe0: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
cff0: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
d000: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
d010: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
d020: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
d030: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
d040: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
d050: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
d060: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
d070: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
d080: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
d090: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
d0a0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
d0b0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
d0c0: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
d0d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
d0e0: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
d0f0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
d100: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
d110: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
d120: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
d130: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
d140: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
d150: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
d160: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
d170: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
d180: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
d190: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
d1a0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
d1b0: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
d1c0: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
d1d0: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
d1e0: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
d1f0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
d200: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
d210: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
d220: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
d230: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
d240: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
d250: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d260: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
d270: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
d280: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
d290: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
d2a0: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
d2b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d2c0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
d2d0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
d2e0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
d2f0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
d300: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
d310: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
d320: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d330: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
d340: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
d350: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
d360: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
d370: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
d380: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
d390: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
d3a0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
d3b0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
d3c0: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
d3d0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d3e0: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
d3f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d400: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
d410: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
d420: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
d430: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
d440: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
d450: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
d460: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
d470: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d480: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
d490: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
d4a0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
d4b0: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
d4c0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
d4d0: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
d4e0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
d4f0: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
d500: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
d510: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
d520: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
d530: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
d540: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
d550: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d560: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
d570: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
d580: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
d590: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
d5a0: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
d5b0: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
d5c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
d5d0: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
d5e0: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
d5f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d600: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
d610: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
d620: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
d630: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d640: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
d650: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
d660: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
d670: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d680: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
d690: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
d6a0: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
d6b0: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
d6c0: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
d6d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
d6e0: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
d6f0: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
d700: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
d710: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
d720: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
d730: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
d740: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
d750: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
d760: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
d770: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
d780: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
d790: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
d7a0: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
d7b0: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
d7c0: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
d7d0: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
d7e0: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
d7f0: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
d800: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
d810: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
d820: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
d830: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
d840: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
d850: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
d860: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d870: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
d880: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
d890: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
d8a0: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
d8b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
d8c0: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
d8d0: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
d8e0: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
d8f0: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
d900: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
d910: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
d920: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
d930: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
d940: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
d950: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
d960: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
d970: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
d980: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
d990: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
d9a0: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
d9b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d9c0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
d9d0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
d9e0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
d9f0: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
da00: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
da10: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
da20: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
da30: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
da40: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
da50: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
da60: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
da70: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
da80: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
da90: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
daa0: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
dab0: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
dac0: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
dad0: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
dae0: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
daf0: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
db00: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
db10: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
db20: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
db30: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
db40: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
db50: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
db60: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
db70: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
db80: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
db90: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
dba0: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
dbb0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
dbc0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
dbd0: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
dbe0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
dbf0: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
dc00: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
dc10: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
dc20: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
dc30: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
dc40: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
dc50: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
dc60: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
dc70: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
dc80: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
dc90: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
dca0: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
dcb0: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
dcc0: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
dcd0: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
dce0: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
dcf0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
dd00: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
dd10: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
dd20: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
dd30: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
dd40: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
dd50: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
dd60: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
dd70: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
dd80: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
dd90: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
dda0: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
ddb0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
ddc0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ddd0: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
dde0: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
ddf0: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
de00: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
de10: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
de20: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
de30: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
de40: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
de50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
de60: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
de70: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
de80: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
de90: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
dea0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
deb0: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
dec0: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
ded0: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
dee0: 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
def0: 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
df00: 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
df10: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
df20: 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
df30: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
df40: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
df50: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
df60: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
df70: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
df80: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
df90: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
dfa0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
dfb0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
dfc0: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
dfd0: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
dfe0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
dff0: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
e000: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
e010: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
e020: 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
e030: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
e040: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
e050: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
e060: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
e070: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
e080: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e090: 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ize(void);.SQLIT
e0a0: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
e0b0: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
e0c0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
e0d0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e0e0: 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
e0f0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
e100: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
e110: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
e120: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
e130: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
e140: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
e150: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
e160: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
e170: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
e180: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
e190: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
e1a0: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
e1b0: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
e1c0: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
e1d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
e1e0: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
e1f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
e200: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
e210: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
e220: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
e230: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
e240: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
e250: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
e260: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
e270: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
e280: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
e290: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
e2a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e2b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
e2c0: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
e2d0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
e2e0: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
e2f0: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
e300: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
e310: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
e320: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
e330: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
e340: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
e350: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
e360: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
e370: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
e380: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
e390: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
e3a0: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
e3b0: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
e3c0: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
e3d0: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
e3e0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
e3f0: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
e400: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
e410: 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
e420: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
e430: 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
e440: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e450: 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
e460: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
e470: 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
e480: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
e490: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
e4a0: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
e4b0: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
e4c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
e4d0: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
e4e0: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
e4f0: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
e500: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
e510: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
e520: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
e530: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
e540: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e550: 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
e560: 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
e570: 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
e580: 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
e590: 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
e5a0: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
e5b0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
e5c0: 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
e5d0: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
e5e0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e5f0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
e600: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e610: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
e620: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
e630: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
e640: 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
e650: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
e660: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
e670: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
e680: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
e690: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
e6a0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
e6b0: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
e6c0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
e6d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
e6e0: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
e6f0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
e700: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
e710: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
e720: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
e730: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
e740: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
e750: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
e760: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
e770: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e780: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
e790: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
e7a0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
e7b0: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
e7c0: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
e7d0: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
e7e0: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
e7f0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
e800: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
e810: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
e820: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
e830: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
e840: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
e850: 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
e860: 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
e870: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
e880: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
e890: 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
e8a0: 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
e8b0: 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
e8c0: 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
e8d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e8e0: 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
e8f0: 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
e900: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
e910: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
e920: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
e930: 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
e940: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
e950: 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
e960: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
e970: 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
e980: 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
e990: 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
e9a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
e9b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
e9c0: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
e9d0: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
e9e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
e9f0: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
ea00: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
ea10: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
ea20: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
ea30: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
ea40: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
ea50: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
ea60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ea70: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
ea80: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
ea90: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
eaa0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
eab0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
eac0: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
ead0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
eae0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
eaf0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
eb00: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
eb10: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
eb20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
eb30: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
eb40: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
eb50: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
eb60: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
eb70: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
eb80: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
eb90: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
eba0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
ebb0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
ebc0: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
ebd0: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
ebe0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
ebf0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
ec00: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
ec10: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
ec20: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ec30: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
ec40: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
ec50: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
ec60: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
ec70: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
ec80: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
ec90: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
eca0: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
ecb0: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
ecc0: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
ecd0: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
ece0: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
ecf0: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
ed00: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
ed10: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
ed20: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
ed30: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
ed40: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
ed50: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
ed60: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
ed70: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
ed80: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
ed90: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
eda0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
edb0: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
edc0: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
edd0: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
ede0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
edf0: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
ee00: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
ee10: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
ee20: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
ee30: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
ee40: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
ee50: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
ee60: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
ee70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
ee80: 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
ee90: 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
eea0: 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
eeb0: 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
eec0: 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
eed0: 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
eee0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
eef0: 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
ef00: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
ef10: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
ef20: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
ef30: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
ef40: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
ef50: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
ef60: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
ef70: 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
ef80: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
ef90: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
efa0: 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
efb0: 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
efc0: 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
efd0: 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
efe0: 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
eff0: 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
f000: 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
f010: 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
f020: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
f030: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
f040: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
f050: 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
f060: 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
f070: 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
f080: 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
f090: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
f0a0: 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
f0b0: 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
f0c0: 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
f0d0: 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
f0e0: 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
f0f0: 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
f100: 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
f110: 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
f120: 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
f130: 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
f140: 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
f150: 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
f160: 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
f170: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
f180: 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
f190: 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
f1a0: 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
f1b0: 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
f1c0: 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
f1d0: 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
f1e0: 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
f1f0: 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
f200: 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
f210: 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
f220: 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
f230: 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
f240: 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
f250: 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
f260: 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65  locator.  (For e
f270: 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
f280: 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
f290: 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
f2a0: 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
f2b0: 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
f2c0: 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
f2d0: 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
f2e0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
f2f0: 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
f300: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
f310: 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
f320: 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
f330: 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
f340: 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
f350: 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
f360: 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
f370: 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
f380: 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
f390: 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
f3a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
f3b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
f3c0: 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
f3d0: 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
f3e0: 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
f3f0: 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
f400: 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
f410: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
f420: 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
f430: 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
f440: 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
f450: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
f460: 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
f470: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
f480: 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
f490: 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
f4a0: 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
f4b0: 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
f4c0: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
f4d0: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
f4e0: 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
f4f0: 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
f500: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
f510: 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
f520: 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
f530: 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
f540: 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
f550: 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
f560: 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
f570: 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
f580: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
f590: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f5a0: 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
f5b0: 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
f5c0: 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
f5d0: 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
f5e0: 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
f5f0: 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
f600: 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
f610: 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
f620: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
f630: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
f640: 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
f650: 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
f660: 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
f670: 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
f680: 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
f690: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
f6a0: 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
f6b0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
f6c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
f6d0: 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
f6e0: 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
f6f0: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
f700: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
f710: 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
f720: 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
f730: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
f740: 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
f750: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
f760: 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
f770: 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
f780: 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
f790: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
f7a0: 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
f7b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
f7c0: 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
f7d0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
f7e0: 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
f7f0: 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
f800: 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
f810: 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
f820: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
f830: 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
f840: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
f850: 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
f860: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
f870: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
f880: 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
f890: 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
f8a0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
f8b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
f8c0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
f8d0: 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
f8e0: 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
f8f0: 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
f900: 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
f910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f920: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
f930: 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
f940: 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
f950: 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
f960: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
f970: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
f980: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
f990: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
f9a0: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
f9b0: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
f9c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
f9d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
f9e0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
f9f0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
fa00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
fa10: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
fa20: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
fa30: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
fa40: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
fa50: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
fa60: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
fa70: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
fa80: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
fa90: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
faa0: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
fab0: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
fac0: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
fad0: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
fae0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
faf0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
fb00: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
fb10: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
fb20: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
fb30: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
fb40: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
fb50: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
fb60: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
fb70: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
fb80: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
fb90: 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
fba0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
fbb0: 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
fbc0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
fbd0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
fbe0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
fbf0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
fc00: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
fc10: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
fc20: 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
fc30: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
fc40: 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
fc50: 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
fc60: 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
fc70: 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
fc80: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
fc90: 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
fca0: 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
fcb0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
fcc0: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
fcd0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
fce0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
fcf0: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
fd00: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
fd10: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
fd20: 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
fd30: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
fd40: 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
fd50: 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
fd60: 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
fd70: 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
fd80: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
fd90: 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
fda0: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
fdb0: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
fdc0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
fdd0: 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
fde0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
fdf0: 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
fe00: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
fe10: 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
fe20: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
fe30: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
fe40: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
fe50: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
fe60: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
fe70: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
fe80: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
fe90: 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
fea0: 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
feb0: 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
fec0: 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
fed0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fee0: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
fef0: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
ff00: 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
ff10: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
ff20: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
ff30: 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
ff40: 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
ff50: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
ff60: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ff70: 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
ff80: 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
ff90: 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
ffa0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
ffb0: 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
ffc0: 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
ffd0: 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
ffe0: 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
fff0: 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
10000 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
10010 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
10020 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
10030 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
10040 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
10050 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
10060 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
10070 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
10080 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
10090 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
100a0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
100b0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
100c0 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
100d0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
100e0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
100f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
10100 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
10110 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
10120 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
10130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
10140 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
10150 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
10160 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
10170 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
10180 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
10190 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
101a0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
101b0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
101c0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
101d0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
101e0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
101f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10200 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
10210 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
10220 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
10230 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
10240 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
10250 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
10260 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
10270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
10280 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
10290 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
102a0 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
102b0 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
102c0 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
102d0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
102e0 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
102f0 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
10300 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
10310 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
10320 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
10330 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
10340 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
10350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
10360 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
10370 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
10380 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
10390 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
103a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
103b0 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
103c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
103d0 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
103e0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
103f0 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
10400 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10410 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
10420 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10430 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
10440 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
10450 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
10460 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
10470 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
10480 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
10490 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
104a0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
104b0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
104c0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
104d0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
104e0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
104f0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
10500 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
10510 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
10520 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10530 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
10540 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
10550 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
10560 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
10570 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
10580 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
10590 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
105a0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
105b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
105c0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
105d0 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
105e0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
105f0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
10600 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
10610 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
10620 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
10630 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
10640 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10650 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
10660 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
10670 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
10680 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
10690 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
106a0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
106b0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
106c0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
106d0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
106e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
106f0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
10700 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
10710 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
10720 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10730 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
10740 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10750 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
10760 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
10770 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
10780 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
10790 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
107a0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
107b0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
107c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
107d0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
107e0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
107f0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
10800 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
10810 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
10820 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
10830 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
10840 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
10850 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
10860 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
10870 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
10880 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
10890 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
108a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
108b0 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
108c0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
108d0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
108e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
108f0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
10900 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
10910 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
10920 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
10930 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10940 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
10950 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
10960 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
10970 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
10980 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
10990 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
109a0 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
109b0 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
109c0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
109d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
109e0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
109f0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a   disabled, the .
10a00 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
10a10 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
10a20 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
10a30 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
10a40 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
10a50 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
10a60 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
10a70 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
10a80 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
10a90 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
10aa0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
10ab0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
10ac0 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
10ad0 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
10ae0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
10af0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
10b00 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
10b10 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
10b20 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
10b30 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
10b40 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
10b50 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
10b60 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
10b70 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
10b80 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
10b90 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
10ba0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
10bb0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
10bc0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
10bd0 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
10be0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
10bf0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
10c00 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
10c10 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
10c20 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
10c30 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
10c40 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
10c50 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
10c60 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
10c70 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
10c80 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
10c90 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
10ca0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
10cb0 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
10cc0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
10cd0 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
10ce0 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
10cf0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
10d00 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
10d10 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
10d20 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
10d30 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
10d40 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a  multiple of 16..
10d50 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10d60 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
10d70 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
10d80 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
10d90 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
10da0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
10db0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
10dc0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
10dd0 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63  more than two sc
10de0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
10df0 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a  r thread.  So.**
10e00 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
10e10 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78   to twice the ex
10e20 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
10e30 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
10e40 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
10e50 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20  l never require 
10e60 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
10e70 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
10e80 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
10e90 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
10ea0 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65  size. ^If SQLite
10eb0 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
10ec0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
10ed0 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
10ee0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
10ef0 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
10f00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
10f10 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
10f20 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
10f30 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
10f40 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
10f50 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eded.</dd>.**.**
10f60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10f70 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
10f80 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
10f90 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
10fa0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
10fb0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
10fc0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
10fd0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
10fe0 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
10ff0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
11000 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
11010 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
11020 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
11030 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
11040 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
11050 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
11060 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
11070 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
11080 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
11090 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
110a0 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
110b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
110c0 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61  tion..** There a
110d0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
110e0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
110f0 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  n: A pointer to 
11100 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
11110 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
11120 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
11130 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
11140 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
11150 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
11160 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
11170 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
11180 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
11190 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
111a0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
111b0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
111c0 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69  32768) plus a li
111d0 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65  ttle extra for e
111e0 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
111f0 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68  er.  ^The page h
11200 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30  eader size is 20
11210 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70   to 40 bytes dep
11220 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65  ending on.** the
11230 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75   host architectu
11240 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d  re.  ^It is harm
11250 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
11260 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
11270 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73  ry,.** to make s
11280 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c  z a little too l
11290 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74  arge.  The first
112a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
112b0 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
112c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
112d0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
112e0 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
112f0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
11300 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
11310 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
11320 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
11330 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
11340 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
11350 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
11360 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
11370 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69  cache.  ^If addi
11380 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
11390 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
113a0 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
113b0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
113c0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
113d0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
113e0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
113f0 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
11400 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
11410 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65  ge space..** The
11420 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
11430 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
11440 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
11450 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
11460 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
11470 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
11480 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
11490 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
114a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
114b0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
114c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
114d0 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
114e0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
114f0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
11500 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
11510 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  er that SQLite w
11520 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61  ill use.** for a
11530 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
11540 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
11550 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64  ion needs beyond
11560 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a   those provided.
11570 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ** for by [SQLIT
11580 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
11590 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
115a0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
115b0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
115c0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
115d0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
115e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
115f0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
11600 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
11610 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
11620 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
11630 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
11640 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
11650 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
11660 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
11670 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
11680 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
11690 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
116a0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
116b0 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
116c0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
116d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
116e0 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
116f0 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
11700 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
11710 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
11720 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
11730 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
11740 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
11750 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
11760 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
11770 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
11780 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
11790 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
117a0 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
117b0 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
117c0 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
117d0 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
117e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
117f0 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
11800 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
11810 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
11820 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
11830 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
11840 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
11850 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
11860 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
11870 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
11880 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
11890 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
118a0 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
118b0 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
118c0 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
118d0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
118e0 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
118f0 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
11900 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11910 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
11920 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11930 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
11940 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
11950 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
11960 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
11970 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
11980 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
11990 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
119a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
119b0 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
119c0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
119d0 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
119e0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
119f0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
11a00 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
11a10 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
11a20 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
11a30 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
11a40 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
11a50 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
11a60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
11a70 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
11a80 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
11a90 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
11aa0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11ab0 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
11ac0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11ad0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11ae0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11af0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11b00 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11b10 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11b20 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
11b30 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
11b40 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
11b50 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
11b60 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
11b70 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11b80 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
11b90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
11ba0 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
11bb0 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
11bc0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
11bd0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
11be0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11bf0 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
11c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11c10 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
11c20 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
11c30 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
11c40 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
11c50 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
11c60 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
11c70 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
11c80 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
11c90 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
11ca0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
11cb0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
11cc0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
11cd0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
11ce0 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
11cf0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
11d00 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
11d10 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
11d20 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
11d30 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
11d40 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
11d50 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
11d60 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
11d70 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
11d80 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
11d90 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
11da0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
11db0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11dc0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11dd0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
11de0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
11df0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
11e00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
11e10 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
11e20 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
11e30 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
11e40 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
11e50 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
11e60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
11e70 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
11e80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
11e90 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
11ea0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
11eb0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
11ec0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
11ed0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11ee0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11ef0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11f00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
11f10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
11f20 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11f30 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
11f40 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
11f50 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
11f60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
11f70 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
11f80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11f90 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
11fa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11fb0 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
11fc0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
11fd0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
11fe0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
11ff0 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
12000 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
12010 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
12020 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
12030 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12040 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
12050 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
12060 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
12070 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
12080 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
12090 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
120a0 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
120b0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
120c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
120d0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
120e0 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
120f0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
12100 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
12110 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
12120 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
12130 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
12140 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12150 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
12160 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
12170 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12180 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12190 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
121a0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
121b0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
121c0 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
121d0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
121e0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
121f0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
12200 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12210 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  n.)^  ^SQLite ma
12220 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
12230 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20  e.** object and 
12240 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65  uses it for page
12250 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c   cache memory al
12260 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a  locations.</dd>.
12270 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12280 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
12290 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
122a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
122b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
122c0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
122d0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
122e0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
122f0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
12300 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
12310 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
12320 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
12330 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
12340 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
12350 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
12360 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
12370 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12380 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
12390 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
123a0 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
123b0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
123c0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
123d0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
123e0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
123f0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
12400 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
12410 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
12420 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
12430 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
12440 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
12450 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
12460 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
12470 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
12480 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
12490 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
124a0 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
124b0 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
124c0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
124d0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
124e0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
124f0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
12500 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
12510 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
12520 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
12530 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
12540 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
12550 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
12560 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
12570 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
12580 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
12590 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
125a0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
125b0 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
125c0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
125d0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
125e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
125f0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
12600 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
12610 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
12620 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
12630 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
12640 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
12650 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
12660 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
12670 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
12680 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
12690 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
126a0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
126b0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
126c0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
126d0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
126e0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
126f0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
12700 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
12710 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
12720 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
12730 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
12740 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
12750 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
12760 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
12770 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
12780 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
12790 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
127a0 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
127b0 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
127c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
127d0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
127e0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
127f0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
12800 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12810 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
12820 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
12830 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  dd> This option 
12840 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12850 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
12860 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  int. If non-zero
12870 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61  , then.** URI ha
12880 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
12890 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
128a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
128b0 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
128c0 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c  andling.** is gl
128d0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
128e0 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67   If URI handling
128f0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
12900 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
12910 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f  mes.** passed to
12920 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
12930 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
12940 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
12950 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
12960 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
12970 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
12980 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
12990 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
129a0 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
129b0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
129c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
129d0 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
129e0 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
129f0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
12a00 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66  on is opened. If
12a10 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
12a20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
12a30 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
12a40 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
12a50 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
12a60 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
12a70 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
12a80 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
12a90 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
12aa0 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  . By default, UR
12ab0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
12ac0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
12ad0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
12ae0 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
12af0 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
12b00 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
12b10 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
12b20 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
12b30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12b40 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b  NFIG_PCACHE]] [[
12b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12b60 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74  TPCACHE]].** <dt
12b70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
12b80 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45  CACHE and SQLITE
12b90 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
12ba0 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20  E.** <dd> These 
12bb0 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f  options are obso
12bc0 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20  lete and should 
12bd0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e  not be used by n
12be0 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79  ew code..** They
12bf0 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
12c00 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
12c10 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72  atibility but ar
12c20 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  e now no-ops..**
12c30 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
12c40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12c50 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
12c60 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
12c70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12c80 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
12c90 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
12ca0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12cb0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
12cc0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
12cd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12ce0 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
12cf0 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
12d00 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
12d10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12d20 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
12d30 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
12d40 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
12d50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12d60 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
12d70 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
12d80 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
12d90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12da0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
12db0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
12dc0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
12dd0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
12de0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
12df0 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
12e00 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
12e10 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
12e20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12e30 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
12e40 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
12e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12e60 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
12e70 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
12e80 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
12e90 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
12ea0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
12eb0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
12ec0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
12ed0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
12ee0 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
12ef0 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
12f00 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
12f10 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
12f20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12f30 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
12f40 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
12f50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12f60 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
12f70 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
12f80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12f90 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
12fa0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
12fb0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
12fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
12fd0 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
12fe0 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
12ff0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13000 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
13010 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
13020 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13030 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
13040 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
13050 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
13060 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
13070 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13080 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
13090 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
130a0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 0a 2f  _methods2* */../
130b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
130c0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
130d0 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
130e0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
130f0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
13100 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
13110 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
13120 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
13130 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
13140 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
13150 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
13160 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
13170 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
13180 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
13190 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
131a0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
131b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
131c0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
131d0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
131e0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
131f0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
13200 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
13210 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
13220 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
13230 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
13240 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
13250 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
13260 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
13270 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
13280 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
13290 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
132a0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
132b0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
132c0 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
132d0 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
132e0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
132f0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
13300 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
13310 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
13320 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
13330 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
13340 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
13350 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
13360 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
13370 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
13380 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
13390 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
133a0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
133b0 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
133c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
133d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
133e0 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
133f0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
13400 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13410 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
13420 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
13430 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
13440 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
13450 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
13460 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
13470 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
13480 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13490 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
134a0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
134b0 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
134c0 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
134d0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
134e0 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
134f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
13500 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
13510 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
13520 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
13530 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
13540 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
13550 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
13560 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
13570 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
13580 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
13590 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
135a0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
135b0 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
135c0 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
135d0 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
135e0 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
135f0 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
13600 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
13610 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
13620 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
13630 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
13640 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
13650 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13660 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
13670 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
13680 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
13690 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
136a0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
136b0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
136c0 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
136d0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
136e0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
136f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13700 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
13710 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
13720 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
13730 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
13740 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
13750 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
13760 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
13770 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
13780 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
13790 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
137a0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
137b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
137c0 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
137d0 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
137e0 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
137f0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
13800 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
13810 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
13820 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
13830 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
13840 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
13850 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
13860 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
13870 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
13880 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
13890 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
138a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
138b0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
138c0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
138d0 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
138e0 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
138f0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
13900 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
13910 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
13920 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
13930 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
13940 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
13950 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
13960 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
13970 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
13980 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
13990 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
139a0 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
139b0 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
139c0 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
139d0 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
139e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
139f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13a00 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
13a10 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
13a20 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
13a30 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
13a40 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
13a50 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
13a60 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
13a70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13a80 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
13a90 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
13aa0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
13ab0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
13ac0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
13ad0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
13ae0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
13af0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
13b00 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
13b10 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
13b20 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
13b30 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
13b40 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
13b50 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
13b60 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
13b70 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
13b80 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
13b90 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13ba0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
13bb0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
13bc0 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
13bd0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
13be0 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
13bf0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
13c00 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
13c10 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
13c20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13c30 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
13c40 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
13c50 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
13c60 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
13c70 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
13c80 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
13c90 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
13ca0 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
13cb0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
13cc0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13cd0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
13ce0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
13cf0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
13d00 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
13d10 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
13d20 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
13d30 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
13d40 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
13d50 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
13d60 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
13d70 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
13d80 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
13d90 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
13da0 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
13db0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
13dc0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
13dd0 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
13de0 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
13df0 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
13e00 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
13e10 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
13e20 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
13e30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
13e40 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
13e50 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
13e60 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
13e70 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
13e80 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
13e90 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
13ea0 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
13eb0 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
13ec0 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
13ed0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
13ee0 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
13ef0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53  patibility..*/.S
13f00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
13f10 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
13f20 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
13f30 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
13f40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13f50 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
13f60 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
13f70 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
13f80 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
13f90 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
13fa0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
13fb0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
13fc0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
13fd0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
13fe0 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
13ff0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
14000 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
14010 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
14020 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
14030 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
14040 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
14050 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
14060 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
14070 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
14080 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
14090 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
140a0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
140b0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
140c0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
140d0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
140e0 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
140f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
14100 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
14110 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
14120 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
14130 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
14140 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
14150 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
14160 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
14170 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14180 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
14190 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
141a0 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
141b0 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
141c0 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
141d0 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
141e0 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
141f0 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
14200 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
14210 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
14220 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
14230 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
14240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
14250 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
14260 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
14270 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
14280 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
14290 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
142a0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
142b0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
142c0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
142d0 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
142e0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
142f0 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
14300 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
14310 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
14320 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
14330 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
14340 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
14350 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
14360 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
14370 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
14380 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
14390 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
143a0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
143b0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
143c0 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
143d0 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
143e0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
143f0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
14400 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
14410 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
14420 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
14430 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
14440 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
14450 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
14460 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
14470 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
14480 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
14490 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
144a0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
144b0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
144c0 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
144d0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
144e0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
144f0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
14500 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
14510 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
14520 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
14530 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
14540 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
14550 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
14560 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
14570 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
14580 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
14590 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
145a0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
145b0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
145c0 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
145d0 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
145e0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
145f0 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
14600 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
14610 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
14620 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
14630 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
14640 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
14650 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
14660 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
14670 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
14680 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
14690 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
146a0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
146b0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
146c0 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
146d0 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
146e0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
146f0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
14700 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
14710 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
14720 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
14730 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
14740 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
14750 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
14760 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
14770 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
14780 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
14790 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
147a0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
147b0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
147c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
147d0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
147e0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
147f0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
14800 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
14810 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
14820 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
14830 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
14840 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
14850 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
14860 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
14870 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
14880 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
14890 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
148a0 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
148b0 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
148c0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
148d0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
148e0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
148f0 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
14900 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
14910 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
14920 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
14930 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
14940 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
14950 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
14960 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
14970 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
14980 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
14990 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
149a0 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73  * ^(Only changes
149b0 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
149c0 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
149d0 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  the [INSERT], [U
149e0 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44  PDATE],.** or [D
149f0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
14a00 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
14a10 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
14a20 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
14a30 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69  iggers or [forei
14a40 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
14a50 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
14a60 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73  )^ Use the.** [s
14a70 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
14a80 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
14a90 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
14aa0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
14ab0 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e  nges.** includin
14ac0 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
14ad0 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64   by triggers and
14ae0 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74   foreign key act
14af0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61  ions..**.** ^Cha
14b00 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
14b10 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
14b20 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
14b30 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
14b40 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
14b50 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
14b60 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
14b70 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  unted..**.** ^(A
14b80 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
14b90 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
14ba0 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
14bb0 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
14bc0 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
14bd0 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
14be0 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
14bf0 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
14c00 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
14c10 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52  de effects of [R
14c20 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
14c30 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
14c40 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
14c50 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44  T processing, [D
14c60 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62  ROP TABLE], or b
14c70 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
14c80 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
14c90 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
14ca0 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a   row changes.)^.
14cb0 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
14cc0 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
14cd0 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
14ce0 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
14cf0 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
14d00 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b  he script of a [
14d10 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
14d20 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d   trigger]. .** M
14d30 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
14d40 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
14d50 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
14d60 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
14d70 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
14d80 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
14d90 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
14da0 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
14db0 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
14dc0 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
14dd0 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
14de0 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
14df0 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
14e00 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
14e10 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
14e20 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
14e30 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
14e40 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
14e50 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
14e60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
14e70 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
14e80 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
14e90 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
14ea0 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
14eb0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
14ec0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
14ed0 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
14ee0 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
14ef0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
14f00 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
14f10 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
14f20 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
14f30 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
14f40 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
14f50 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
14f60 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
14f70 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
14f80 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
14f90 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
14fa0 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
14fb0 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
14fc0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
14fd0 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
14fe0 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
14ff0 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68  p level.  ^(With
15000 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
15010 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
15020 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
15030 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
15040 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
15050 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
15060 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
15070 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
15080 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
15090 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
150a0 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
150b0 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
150c0 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
150d0 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
150e0 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
150f0 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
15100 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
15110 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
15120 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
15130 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
15140 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a  own context.)^.*
15150 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
15160 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
15170 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
15180 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
15190 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
151a0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
151b0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
151c0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
151d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
151e0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
151f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
15200 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15210 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
15220 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
15230 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
15240 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
15250 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
15260 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
15270 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
15280 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
15290 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
152a0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
152b0 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
152c0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
152d0 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
152e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
152f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
15300 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
15310 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
15320 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
15330 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
15340 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
15350 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15360 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
15370 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
15380 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
15390 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
153a0 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
153b0 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
153c0 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
153d0 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
153e0 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
153f0 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
15400 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
15410 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
15420 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
15430 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
15440 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
15450 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
15460 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
15470 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
15480 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
15490 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
154a0 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
154b0 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
154c0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
154d0 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
154e0 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
154f0 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
15500 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
15510 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
15520 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
15530 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
15540 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
15550 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
15560 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
15570 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
15580 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
15590 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
155a0 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
155b0 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
155c0 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
155d0 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
155e0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
155f0 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
15600 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
15610 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
15620 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
15630 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
15640 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
15650 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
15660 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
15670 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
15680 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
15690 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
156a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
156b0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
156c0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
156d0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
156e0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
156f0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
15700 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
15710 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
15720 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
15730 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
15740 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
15750 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
15760 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
15770 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
15780 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
15790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
157a0 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
157b0 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
157c0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
157d0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
157e0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
157f0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
15800 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
15810 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
15820 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
15830 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
15840 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
15850 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
15860 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
15870 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
15880 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
15890 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
158a0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
158b0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
158c0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
158d0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
158e0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
158f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
15900 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
15910 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
15920 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
15930 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
15940 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
15950 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
15960 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
15970 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
15980 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
15990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
159a0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
159b0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
159c0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
159d0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
159e0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
159f0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
15a00 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
15a10 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
15a20 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
15a30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
15a40 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
15a50 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
15a60 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
15a70 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
15a80 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
15a90 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
15aa0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
15ab0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
15ac0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
15ad0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
15ae0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
15af0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
15b00 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
15b10 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
15b20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
15b30 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
15b40 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
15b50 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
15b60 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
15b70 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
15b80 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
15b90 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
15ba0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
15bb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
15bc0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
15bd0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
15be0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
15bf0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
15c00 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
15c10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15c20 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
15c30 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
15c40 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
15c50 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
15c60 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
15c70 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
15c80 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
15c90 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
15ca0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
15cb0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
15cc0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
15cd0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
15ce0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
15cf0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15d00 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
15d10 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
15d20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
15d30 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
15d40 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
15d50 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
15d60 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
15d70 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
15d80 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
15d90 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
15da0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15db0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
15dc0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
15dd0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
15de0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
15df0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
15e00 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
15e10 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
15e20 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
15e30 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
15e40 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
15e50 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
15e60 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
15e70 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
15e80 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
15e90 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
15ea0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
15eb0 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
15ec0 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
15ed0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
15ee0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
15ef0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
15f00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15f10 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
15f20 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
15f30 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
15f40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
15f50 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
15f60 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
15f70 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
15f80 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
15f90 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
15fa0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
15fb0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
15fc0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
15fd0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
15fe0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
15ff0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
16000 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
16010 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
16020 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
16030 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
16040 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
16050 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
16060 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
16070 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
16080 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
16090 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
160a0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
160b0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
160c0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
160d0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
160e0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
160f0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
16100 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
16110 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
16120 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
16130 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
16140 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
16150 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
16160 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
16170 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
16180 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
16190 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
161a0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
161b0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
161c0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
161d0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
161e0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
161f0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
16200 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
16210 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
16220 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
16230 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
16240 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
16250 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
16260 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
16270 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
16280 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
16290 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
162a0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
162b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
162c0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
162d0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
162e0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
162f0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
16300 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
16310 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
16320 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
16330 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
16340 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
16350 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
16360 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
16370 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
16380 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
16390 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
163a0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
163b0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
163c0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
163d0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
163e0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
163f0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
16400 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
16410 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
16420 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
16430 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
16440 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
16450 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
16460 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
16470 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
16480 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
16490 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
164a0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
164b0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
164c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
164d0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
164e0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
164f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
16500 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
16510 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
16520 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
16530 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
16540 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
16550 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
16560 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
16570 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51  t char *sql);.SQ
16580 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
16590 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
165a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
165b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
165c0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
165d0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
165e0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
165f0 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
16600 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
16610 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
16620 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
16630 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
16640 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
16650 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
16660 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
16670 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
16680 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
16690 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
166a0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
166b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
166c0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
166d0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
166e0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
166f0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
16700 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
16710 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
16720 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
16730 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
16740 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
16750 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
16760 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
16770 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
16780 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
16790 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
167a0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
167b0 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
167c0 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
167d0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
167e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
167f0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
16800 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
16810 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16820 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
16830 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
16840 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
16850 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
16860 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
16870 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
16880 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
16890 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
168a0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
168b0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
168c0 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
168d0 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
168e0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
168f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
16900 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
16910 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
16920 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
16930 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
16940 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
16950 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
16960 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
16970 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
16980 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
16990 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
169a0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
169b0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
169c0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
169d0 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
169e0 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
169f0 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
16a00 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
16a10 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
16a20 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
16a30 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
16a40 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
16a50 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
16a60 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
16a70 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
16a80 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
16a90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
16aa0 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
16ab0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
16ac0 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
16ad0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
16ae0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
16af0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
16b00 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
16b10 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
16b20 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
16b30 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
16b40 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
16b50 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
16b60 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
16b70 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
16b80 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
16b90 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
16ba0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
16bb0 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
16bc0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
16bd0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
16be0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
16bf0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
16c00 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
16c10 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
16c20 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
16c30 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
16c40 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
16c50 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
16c60 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
16c70 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
16c80 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
16c90 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
16ca0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
16cb0 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
16cc0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
16cd0 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
16ce0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
16cf0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
16d00 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
16d10 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
16d20 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
16d30 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
16d40 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
16d50 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
16d60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
16d70 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
16d80 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
16d90 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
16da0 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
16db0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
16dc0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
16dd0 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
16de0 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
16df0 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
16e00 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
16e10 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
16e20 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
16e30 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
16e40 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
16e50 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
16e60 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
16e70 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
16e80 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
16e90 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
16ea0 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
16eb0 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
16ec0 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
16ed0 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
16ee0 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
16ef0 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
16f00 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
16f10 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
16f20 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
16f30 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
16f40 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
16f50 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
16f60 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
16f70 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
16f80 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
16f90 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
16fa0 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
16fb0 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
16fc0 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
16fd0 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
16fe0 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
16ff0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
17000 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
17010 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
17020 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
17030 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
17040 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
17050 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
17060 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
17070 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
17080 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
17090 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
170a0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
170b0 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
170c0 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
170d0 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
170e0 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
170f0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
17100 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
17110 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
17120 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
17130 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
17140 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
17150 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
17160 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
17170 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
17180 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
17190 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
171a0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
171b0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
171c0 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
171d0 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
171e0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
171f0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
17200 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
17210 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
17220 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
17230 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
17240 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
17250 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
17260 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
17270 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
17280 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
17290 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
172a0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
172b0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
172c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
172d0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
172e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
172f0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
17300 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
17310 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
17320 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
17330 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
17340 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
17350 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
17360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
17370 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
17380 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
17390 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
173a0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
173b0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
173c0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
173d0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
173e0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
173f0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
17400 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
17410 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
17420 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
17430 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
17440 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
17450 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
17460 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
17470 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
17480 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
17490 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
174a0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
174b0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
174c0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
174d0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
174e0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
174f0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
17500 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
17510 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
17520 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
17530 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
17540 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
17550 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
17560 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
17570 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
17580 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
17590 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
175a0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
175b0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
175c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
175d0 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
175e0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
175f0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
17600 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
17610 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
17620 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
17630 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
17640 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
17650 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
17660 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
17670 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51  cleared.)^.*/.SQ
17680 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
17690 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
176a0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
176b0 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
176c0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
176d0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
176e0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
176f0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
17700 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
17710 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
17720 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
17730 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
17740 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
17750 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
17760 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
17770 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
17780 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
17790 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
177a0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
177b0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
177c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
177d0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
177e0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
177f0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
17800 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
17810 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
17820 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
17830 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
17840 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
17850 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
17860 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
17870 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
17880 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
17890 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
178a0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
178b0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
178c0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
178d0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
178e0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
178f0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
17900 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
17910 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
17920 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
17930 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
17940 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
17950 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
17960 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
17970 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
17980 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
17990 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
179a0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
179b0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
179c0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
179d0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
179e0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
179f0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
17a00 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
17a10 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
17a20 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
17a30 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
17a40 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
17a50 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
17a60 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
17a70 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
17a80 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
17a90 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
17aa0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
17ab0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
17ac0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
17ad0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
17ae0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
17af0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
17b00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
17b10 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
17b20 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
17b30 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
17b40 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
17b50 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
17b60 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
17b70 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
17b80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
17b90 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
17ba0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
17bb0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
17bc0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
17bd0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
17be0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
17bf0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
17c00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
17c10 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
17c20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
17c30 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
17c40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
17c50 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
17c60 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
17c70 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
17c80 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
17c90 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
17ca0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
17cb0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
17cc0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
17cd0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
17ce0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
17cf0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
17d00 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
17d10 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
17d20 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
17d30 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
17d40 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
17d50 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
17d60 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
17d70 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
17d80 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
17d90 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
17da0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
17db0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
17dc0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
17dd0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
17de0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
17df0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
17e00 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
17e10 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
17e20 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
17e30 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
17e40 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
17e50 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
17e60 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
17e70 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
17e80 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
17e90 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
17ea0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
17eb0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
17ec0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
17ed0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
17ee0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
17ef0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
17f00 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
17f10 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
17f20 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
17f30 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
17f40 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
17f50 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
17f60 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
17f70 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
17f80 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
17f90 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
17fa0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
17fb0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
17fc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
17fd0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
17fe0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
17ff0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
18000 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
18010 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
18020 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
18030 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
18040 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
18050 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
18060 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
18070 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
18080 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
18090 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
180a0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
180b0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
180c0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
180d0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
180e0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
180f0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
18100 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
18110 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
18120 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
18130 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
18140 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
18150 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
18160 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
18170 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
18180 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
18190 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
181a0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
181b0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
181c0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
181d0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
181e0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
181f0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
18200 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
18210 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
18220 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
18230 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
18240 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
18250 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
18260 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
18270 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
18280 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
18290 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
182a0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
182b0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
182c0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
182d0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
182e0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
182f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
18300 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
18310 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
18320 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
18330 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
18340 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
18350 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
18360 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
18370 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
18380 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
18390 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
183a0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
183b0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
183c0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
183d0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
183e0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
183f0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
18400 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
18410 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
18420 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
18430 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
18440 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
18450 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
18460 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
18470 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
18480 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
18490 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
184a0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
184b0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
184c0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
184d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
184e0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
184f0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
18500 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
18510 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
18520 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
18530 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
18540 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
18550 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
18560 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
18570 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18580 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
18590 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
185a0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
185b0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
185c0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
185d0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
185e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
185f0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
18600 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
18610 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
18620 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
18630 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
18640 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
18650 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
18660 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
18670 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
18680 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
18690 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
186a0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
186b0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
186c0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
186d0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
186e0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
186f0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
18700 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
18710 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
18720 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
18730 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
18740 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
18750 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
18760 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
18770 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
18780 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
18790 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
187a0 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
187b0 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
187c0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
187d0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
187e0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
187f0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
18800 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
18810 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
18820 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
18830 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
18840 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
18850 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
18860 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
18870 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
18880 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
18890 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
188a0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
188b0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
188c0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
188d0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
188e0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
188f0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
18900 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
18910 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
18920 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
18930 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
18940 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
18950 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
18960 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
18970 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
18980 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
18990 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
189a0 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
189b0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
189c0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
189d0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
189e0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
189f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
18a00 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
18a10 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
18a20 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
18a30 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
18a40 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
18a50 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
18a60 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
18a70 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
18a80 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
18a90 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
18aa0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
18ab0 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
18ac0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
18ad0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
18ae0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
18af0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18b00 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
18b10 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
18b20 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
18b30 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
18b40 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
18b50 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
18b60 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
18b70 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
18b80 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
18b90 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
18ba0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
18bb0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
18bc0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
18bd0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
18be0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
18bf0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
18c00 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
18c10 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
18c20 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
18c30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
18c40 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
18c50 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
18c60 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
18c70 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
18c80 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
18c90 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
18ca0 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
18cb0 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
18cc0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
18cd0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
18ce0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
18cf0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
18d00 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
18d10 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
18d20 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
18d30 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
18d40 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
18d50 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
18d60 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
18d70 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
18d80 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
18d90 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
18da0 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
18db0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
18dc0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
18dd0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
18de0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
18df0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
18e00 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
18e10 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
18e20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
18e30 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18e40 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
18e50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
18e60 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
18e70 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
18e80 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
18e90 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
18ea0 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
18eb0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
18ec0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
18ed0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
18ee0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
18ef0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
18f00 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
18f10 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
18f20 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
18f30 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
18f40 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
18f50 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
18f60 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
18f70 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
18f80 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
18f90 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
18fa0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
18fb0 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
18fc0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
18fd0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
18fe0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
18ff0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
19000 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
19010 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
19020 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
19030 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
19040 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
19050 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
19060 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
19070 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
19080 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
19090 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
190a0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
190b0 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
190c0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
190d0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
190e0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
190f0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
19100 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
19110 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
19120 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
19130 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
19140 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
19150 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
19160 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
19170 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
19180 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
19190 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
191a0 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
191b0 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
191c0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
191d0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
191e0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
191f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
19200 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
19210 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
19220 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
19230 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
19240 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
19250 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
19260 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19270 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
19280 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
19290 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
192a0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
192b0 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
192c0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
192d0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
192e0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
192f0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
19300 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
19310 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
19320 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
19330 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
19340 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
19350 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
19360 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
19370 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
19380 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
19390 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
193a0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
193b0 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
193c0 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
193d0 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
193e0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
193f0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
19400 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
19410 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
19420 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
19430 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
19440 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
19450 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  ing.)^.*/.SQLITE
19460 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
19470 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
19480 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c   char*,...);.SQL
19490 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
194a0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
194b0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
194c0 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ist);.SQLITE_API
194d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
194e0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
194f0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
19500 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
19510 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
19520 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
19530 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
19540 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
19550 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
19560 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
19570 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
19580 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
19590 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
195a0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
195b0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
195c0 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
195d0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
195e0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
195f0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
19600 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
19610 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
19620 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
19630 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
19640 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
19650 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
19660 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
19670 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
19680 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
19690 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
196a0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
196b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
196c0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
196d0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
196e0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
196f0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
19700 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
19710 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
19720 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
19730 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
19740 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
19750 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
19760 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
19770 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
19780 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
19790 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
197a0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
197b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
197c0 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
197d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
197e0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
197f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
19800 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
19810 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
19820 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
19830 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
19840 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
19850 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
19860 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
19870 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
19880 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
19890 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
198a0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
198b0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
198c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
198d0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
198e0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
198f0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
19900 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
19910 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
19920 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
19930 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
19940 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
19950 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
19960 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
19970 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
19980 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
19990 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
199a0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
199b0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
199c0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
199d0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
199e0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
199f0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
19a00 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
19a10 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
19a20 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
19a30 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
19a40 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
19a50 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
19a60 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
19a70 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
19a80 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
19a90 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
19aa0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
19ab0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
19ac0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
19ad0 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
19ae0 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
19af0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
19b00 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
19b10 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
19b20 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
19b30 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
19b40 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
19b50 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
19b60 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19b70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
19b80 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
19b90 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
19ba0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
19bb0 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
19bc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
19bd0 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
19be0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19bf0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
19c00 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
19c10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19c20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
19c30 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
19c40 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
19c50 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
19c60 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
19c70 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
19c80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
19c90 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
19ca0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19cb0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
19cc0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
19cd0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
19ce0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
19cf0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
19d00 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
19d10 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
19d20 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
19d30 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
19d40 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
19d50 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
19d60 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
19d70 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
19d80 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
19d90 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
19da0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
19db0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
19dc0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
19dd0 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
19de0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
19df0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
19e00 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
19e10 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
19e20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
19e30 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
19e40 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
19e50 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
19e60 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
19e70 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
19e80 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
19e90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
19ea0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
19eb0 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
19ec0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
19ed0 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
19ee0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
19ef0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
19f00 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
19f10 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
19f20 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
19f30 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
19f40 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
19f50 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
19f60 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
19f70 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
19f80 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
19f90 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
19fa0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
19fb0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
19fc0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
19fd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
19fe0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
19ff0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1a000 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1a010 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1a020 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1a030 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1a040 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1a050 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1a060 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
1a070 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1a080 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
1a090 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
1a0a0 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
1a0b0 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
1a0c0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
1a0d0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
1a0e0 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
1a0f0 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
1a100 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
1a110 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
1a120 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
1a130 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
1a140 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
1a150 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
1a160 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
1a170 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
1a180 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
1a190 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
1a1a0 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
1a1b0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
1a1c0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
1a1d0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
1a1e0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
1a1f0 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
1a200 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
1a210 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a220 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
1a230 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
1a240 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
1a250 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
1a260 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
1a270 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1a280 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
1a290 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
1a2a0 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
1a2b0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
1a2c0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
1a2d0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
1a2e0 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
1a2f0 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
1a300 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
1a310 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
1a320 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
1a330 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
1a340 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1a350 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51  ealloc()]..*/.SQ
1a360 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
1a370 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
1a380 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1a390 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1a3a0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1a3b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1a3c0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
1a3d0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1a3e0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1a3f0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1a400 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1a410 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1a420 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1a430 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1a440 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1a450 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1a460 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1a470 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1a480 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a490 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1a4a0 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1a4b0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1a4c0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1a4d0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1a4e0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1a4f0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1a500 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1a510 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1a520 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1a530 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1a540 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1a550 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1a560 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1a570 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1a580 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1a590 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1a5a0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1a5b0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1a5c0 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1a5d0 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1a5e0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1a5f0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1a600 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1a610 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1a620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1a630 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1a640 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1a650 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1a660 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1a670 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1a680 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1a690 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1a6a0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1a6b0 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1a6c0 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1a6d0 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1a6e0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1a6f0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1a700 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1a710 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1a720 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1a730 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1a740 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1a750 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1a760 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1a770 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1a780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1a790 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1a7a0 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1a7b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1a7c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1a7d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1a7e0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1a7f0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1a800 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1a810 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
1a820 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1a830 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1a840 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
1a850 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
1a860 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1a870 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1a880 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1a890 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1a8a0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1a8b0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1a8c0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1a8d0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1a8e0 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1a8f0 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1a900 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1a910 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1a920 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1a930 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1a940 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1a950 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1a960 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1a970 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1a980 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1a990 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1a9a0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1a9b0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1a9c0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1a9d0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1a9e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1a9f0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1aa00 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1aa10 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1aa20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1aa30 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1aa40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1aa50 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1aa60 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1aa70 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
1aa80 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
1aa90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
1aaa0 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20  invoked (either 
1aab0 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79  internally or by
1aac0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
1aad0 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73  ion) the PRNG is
1aae0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
1aaf0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
1ab00 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52  d.** from the xR
1ab10 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
1ab20 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
1ab30 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1ab40 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c  ject..** ^On all
1ab50 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
1ab60 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65  cations, the pse
1ab70 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1ab80 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1ab90 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1aba0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1abb0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1abc0 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1abd0 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51  ** method..*/.SQ
1abe0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1abf0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1ac00 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1ac10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ac20 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1ac30 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1ac40 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1ac50 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
1ac60 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
1ac70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
1ac80 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
1ac90 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1aca0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
1acb0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
1acc0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
1acd0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ace0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1acf0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
1ad00 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
1ad10 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
1ad20 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1ad30 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
1ad40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ad50 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
1ad60 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1ad70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1ad80 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
1ad90 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
1ada0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
1adb0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
1adc0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
1add0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
1ade0 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
1adf0 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
1ae00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ae10 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1ae20 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
1ae30 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
1ae40 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
1ae50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ae60 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
1ae70 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1ae80 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
1ae90 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
1aea0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
1aeb0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1aec0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
1aed0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
1aee0 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
1aef0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
1af00 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
1af10 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
1af20 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
1af30 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
1af40 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
1af50 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
1af60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1af70 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
1af80 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1af90 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
1afa0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
1afb0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1afc0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
1afd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1afe0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1aff0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1b000 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
1b010 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1b020 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1b030 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1b040 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
1b050 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1b060 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
1b070 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
1b080 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
1b090 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
1b0a0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b0b0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
1b0c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1b0d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1b0e0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1b0f0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
1b100 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1b110 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1b120 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1b130 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
1b140 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
1b150 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
1b160 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b170 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1b180 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1b190 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1b1a0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
1b1b0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1b1c0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1b1d0 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
1b1e0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1b1f0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
1b200 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1b210 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
1b220 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
1b230 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1b240 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
1b250 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1b260 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
1b270 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
1b280 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
1b290 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1b2a0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
1b2b0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1b2c0 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
1b2d0 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
1b2e0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
1b2f0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1b300 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1b310 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1b320 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
1b330 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1b340 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1b350 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1b360 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1b370 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
1b380 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
1b390 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
1b3a0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
1b3b0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
1b3c0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
1b3d0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
1b3e0 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
1b3f0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
1b400 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
1b410 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
1b420 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
1b430 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
1b440 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
1b450 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
1b460 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
1b470 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
1b480 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1b490 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1b4a0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
1b4b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1b4c0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
1b4d0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
1b4e0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
1b4f0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
1b500 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
1b510 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
1b520 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
1b530 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
1b540 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
1b550 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
1b560 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
1b570 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b580 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
1b590 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1b5a0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
1b5b0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
1b5c0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
1b5d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1b5e0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
1b5f0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
1b600 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
1b610 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
1b620 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
1b630 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
1b640 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
1b650 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
1b660 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
1b670 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
1b680 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
1b690 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
1b6a0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
1b6b0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
1b6c0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
1b6d0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
1b6e0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1b6f0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
1b700 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
1b710 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
1b720 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
1b730 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
1b740 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
1b750 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
1b760 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
1b770 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
1b780 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
1b790 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
1b7a0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
1b7b0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
1b7c0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
1b7d0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
1b7e0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1b7f0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
1b800 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
1b810 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
1b820 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
1b830 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
1b840 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
1b850 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
1b860 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1b870 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
1b880 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
1b890 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
1b8a0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
1b8b0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
1b8c0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
1b8d0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
1b8e0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
1b8f0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
1b900 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
1b910 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
1b920 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
1b930 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
1b940 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
1b950 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
1b960 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
1b970 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
1b980 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
1b990 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
1b9a0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
1b9b0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
1b9c0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
1b9d0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
1b9e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
1b9f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1ba00 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1ba10 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1ba20 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1ba30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ba40 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1ba50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ba60 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
1ba70 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1ba80 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1ba90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1baa0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1bab0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1bac0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1bad0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1bae0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1baf0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
1bb00 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1bb10 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
1bb20 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
1bb30 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
1bb40 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
1bb50 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
1bb60 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
1bb70 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
1bb80 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
1bb90 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
1bba0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
1bbb0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
1bbc0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
1bbd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1bbe0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
1bbf0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
1bc00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1bc10 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
1bc20 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
1bc30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1bc40 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
1bc50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1bc60 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1bc70 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
1bc80 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
1bc90 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
1bca0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
1bcb0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
1bcc0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
1bcd0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
1bce0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1bcf0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
1bd00 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
1bd10 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
1bd20 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
1bd30 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1bd40 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
1bd50 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51  ma change..*/.SQ
1bd60 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1bd70 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1bd80 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
1bd90 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
1bda0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1bdb0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1bdc0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1bdd0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
1bde0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
1bdf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1be00 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
1be10 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
1be20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1be30 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1be40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1be50 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
1be60 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
1be70 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
1be80 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
1be90 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
1bea0 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
1beb0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
1bec0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
1bed0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
1bee0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
1bef0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1bf00 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1bf10 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
1bf20 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1bf30 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1bf40 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
1bf50 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
1bf60 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
1bf70 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
1bf80 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a   | return code].
1bf90 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ** from the [sql
1bfa0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
1bfb0 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
1bfc0 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
1bfd0 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
1bfe0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
1bff0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
1c000 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
1c010 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
1c020 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
1c030 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
1c040 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
1c050 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
1c060 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1c070 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
1c080 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1c090 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1c0a0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1c0b0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
1c0c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1c0d0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
1c0e0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
1c0f0 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
1c100 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
1c110 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1c120 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c130 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1c140 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
1c150 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1c160 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
1c170 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
1c180 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
1c190 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
1c1a0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
1c1b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1c1c0 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
1c1d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1c1e0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
1c1f0 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
1c200 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
1c210 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
1c220 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
1c230 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
1c240 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
1c250 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
1c260 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1c270 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
1c280 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
1c290 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
1c2a0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
1c2b0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
1c2c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1c2d0 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
1c2e0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
1c2f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c300 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
1c310 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1c320 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
1c330 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
1c340 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
1c350 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
1c360 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1c370 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1c380 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1c390 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
1c3a0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
1c3b0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1c3c0 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
1c3d0 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1c3e0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1c3f0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1c400 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
1c410 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
1c420 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1c430 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c440 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
1c450 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
1c460 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
1c470 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c480 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
1c490 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
1c4a0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1c4b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1c4c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c4d0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
1c4e0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
1c4f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1c500 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1c510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1c520 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
1c530 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
1c540 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1c550 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1c560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1c570 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
1c580 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
1c590 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1c5a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1c5b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1c5c0 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
1c5d0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
1c5e0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1c5f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1c600 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1c610 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
1c620 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
1c630 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1c640 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c650 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1c660 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1c670 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
1c680 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1c690 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1c6a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1c6b0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1c6c0 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
1c6d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1c6e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1c6f0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
1c700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
1c710 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1c720 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c730 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c740 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
1c750 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
1c760 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1c770 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1c780 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c790 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
1c7a0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
1c7b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c7c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c7d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c7e0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1c7f0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
1c800 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1c810 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1c820 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c830 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1c840 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
1c850 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c860 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c870 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c880 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
1c890 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
1c8a0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1c8b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c8c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c8d0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
1c8e0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
1c8f0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1c900 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c910 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c920 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
1c930 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
1c940 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1c950 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1c960 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c970 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
1c980 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
1c990 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1c9a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1c9b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c9c0 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
1c9d0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
1c9e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1c9f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ca00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
1ca10 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
1ca20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
1ca30 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
1ca40 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
1ca50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1ca60 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
1ca70 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
1ca80 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1ca90 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1caa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
1cab0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
1cac0 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
1cad0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
1cae0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1caf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
1cb00 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
1cb10 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
1cb20 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
1cb30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1cb40 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
1cb50 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1cb60 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
1cb70 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1cb80 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1cb90 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
1cba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1cbb0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
1cbc0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1cbd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1cbe0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
1cbf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
1cc00 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1cc10 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
1cc20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1cc30 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
1cc40 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
1cc50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1cc60 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
1cc70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1cc80 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
1cc90 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
1cca0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1ccb0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ccc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ccd0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
1cce0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
1ccf0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1cd00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1cd10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1cd20 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
1cd30 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
1cd40 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1cd50 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1cd60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cd70 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
1cd80 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
1cd90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1cda0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1cdb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1cdc0 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
1cdd0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
1cde0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1cdf0 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
1ce00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ce10 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
1ce20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
1ce30 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
1ce40 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
1ce50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ce60 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
1ce70 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
1ce80 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
1ce90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cea0 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
1ceb0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
1cec0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1ced0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
1cee0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1cef0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
1cf00 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
1cf10 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
1cf20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
1cf30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1cf40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1cf50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1cf60 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1cf70 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
1cf80 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
1cf90 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
1cfa0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1cfb0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
1cfc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1cfd0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
1cfe0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1cff0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
1d000 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
1d010 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
1d020 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
1d030 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
1d040 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
1d050 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
1d060 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
1d070 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
1d080 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
1d090 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
1d0a0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
1d0b0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
1d0c0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
1d0d0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
1d0e0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
1d0f0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
1d100 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
1d110 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  gger.)^.**.** ^T
1d120 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1d130 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1d140 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
1d150 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
1d160 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
1d170 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
1d180 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
1d190 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
1d1a0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
1d1b0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
1d1c0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
1d1d0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
1d1e0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
1d1f0 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
1d200 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
1d210 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1d220 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
1d230 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
1d240 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
1d250 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
1d260 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
1d270 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
1d280 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
1d290 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
1d2a0 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
1d2b0 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
1d2c0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
1d2d0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
1d2e0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1d2f0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
1d300 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
1d310 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
1d320 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
1d330 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
1d340 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1d350 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
1d360 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
1d370 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
1d380 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1d390 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
1d3a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
1d3b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1d3c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
1d3d0 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
1d3e0 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
1d3f0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
1d400 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  id*);.SQLITE_API
1d410 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45   SQLITE_EXPERIME
1d420 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1d430 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
1d440 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
1d450 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
1d460 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
1d470 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
1d480 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d490 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
1d4a0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
1d4b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1d4c0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1d4d0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
1d4e0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
1d4f0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1d500 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
1d510 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1d520 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1d530 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1d540 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1d550 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
1d560 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1d570 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
1d580 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1d590 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
1d5a0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
1d5b0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
1d5c0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
1d5d0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
1d5e0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
1d5f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
1d600 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
1d610 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
1d620 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
1d630 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
1d640 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
1d650 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1d660 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  N is the number 
1d670 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
1d680 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
1d690 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
1d6a0 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
1d6b0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
1d6c0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
1d6d0 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a  e callback X..**
1d6e0 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
1d6f0 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
1d700 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
1d710 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
1d720 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
1d730 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
1d740 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
1d750 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
1d760 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
1d770 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
1d780 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
1d790 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
1d7a0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1d7b0 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
1d7c0 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
1d7d0 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
1d7e0 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
1d7f0 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
1d800 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
1d810 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1d820 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1d830 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
1d840 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
1d850 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
1d860 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
1d870 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
1d880 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
1d890 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
1d8a0 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
1d8b0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
1d8c0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
1d8d0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1d8e0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1d8f0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1d900 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d910 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1d920 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
1d930 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
1d940 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1d950 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1d960 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d970 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1d980 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1d990 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1d9a0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1d9b0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1d9c0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
1d9d0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1d9e0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1d9f0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1da00 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
1da10 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
1da20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1da30 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
1da40 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
1da50 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
1da60 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
1da70 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1da80 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
1da90 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
1daa0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
1dab0 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
1dac0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
1dad0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
1dae0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1daf0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1db00 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
1db10 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1db20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
1db30 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
1db40 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
1db50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1db60 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
1db70 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
1db80 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
1db90 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
1dba0 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
1dbb0 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
1dbc0 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
1dbd0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1dbe0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
1dbf0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
1dc00 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
1dc10 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
1dc20 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
1dc30 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
1dc40 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
1dc50 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
1dc60 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
1dc70 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
1dc80 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
1dc90 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
1dca0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
1dcb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
1dcc0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1dcd0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1dce0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
1dcf0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1dd00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
1dd10 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
1dd20 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
1dd30 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
1dd40 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
1dd50 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
1dd60 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
1dd70 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
1dd80 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
1dd90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
1dda0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
1ddb0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
1ddc0 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
1ddd0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
1dde0 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
1ddf0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1de00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1de10 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
1de20 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1de30 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
1de40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1de50 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
1de60 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
1de70 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
1de80 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
1de90 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
1dea0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1deb0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1dec0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1ded0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
1dee0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
1def0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
1df00 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
1df10 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
1df20 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
1df30 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
1df40 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
1df50 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
1df60 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
1df70 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
1df80 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
1df90 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
1dfa0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
1dfb0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
1dfc0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1dfd0 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
1dfe0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
1dff0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1e000 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
1e010 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
1e020 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
1e030 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
1e040 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
1e050 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1e060 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1e070 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1e080 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1e090 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1e0a0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
1e0b0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1e0c0 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
1e0d0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
1e0e0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
1e0f0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1e100 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
1e110 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1e120 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1e130 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
1e140 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
1e150 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1e160 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
1e170 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1e180 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1e190 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1e1a0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1e1b0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1e1c0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1e1d0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1e1e0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1e1f0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
1e200 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
1e210 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
1e220 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
1e230 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1e240 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
1e250 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
1e260 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
1e270 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
1e280 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
1e290 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1e2a0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1e2b0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1e2c0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
1e2d0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
1e2e0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1e2f0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1e300 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1e310 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
1e320 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
1e330 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
1e340 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
1e350 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
1e360 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
1e370 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1e380 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1e390 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
1e3a0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
1e3b0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
1e3c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1e3d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
1e3e0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
1e3f0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1e400 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
1e410 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1e420 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
1e430 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1e440 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
1e450 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
1e460 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1e470 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1e480 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
1e490 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
1e4a0 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
1e4b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1e4c0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
1e4d0 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
1e4e0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
1e4f0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
1e500 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
1e510 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
1e520 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
1e530 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1e540 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
1e550 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1e560 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
1e570 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
1e580 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1e590 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
1e5a0 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
1e5b0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1e5c0 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
1e5d0 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
1e5e0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
1e5f0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
1e600 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1e610 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
1e620 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1e630 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1e640 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1e650 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
1e660 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
1e670 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
1e680 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
1e690 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1e6a0 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
1e6b0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
1e6c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
1e6d0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
1e6e0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
1e6f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
1e700 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
1e710 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1e720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1e730 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
1e740 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
1e750 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
1e760 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
1e770 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
1e780 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1e790 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1e7a0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1e7b0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1e7c0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1e7d0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1e7e0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1e7f0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1e800 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1e810 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1e820 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
1e830 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1e840 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1e850 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1e860 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1e870 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1e880 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
1e890 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1e8a0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1e8b0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1e8c0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1e8d0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1e8e0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1e8f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1e900 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1e910 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1e920 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1e930 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e940 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1e950 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1e960 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1e970 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1e980 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1e990 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1e9a0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1e9b0 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1e9c0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1e9d0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1e9e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1e9f0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1ea00 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1ea10 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1ea20 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1ea30 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1ea40 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1ea50 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1ea60 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1ea70 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1ea80 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1ea90 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1eaa0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1eab0 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1eac0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1ead0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
1eae0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
1eaf0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
1eb00 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
1eb10 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
1eb20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1eb30 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1eb40 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
1eb50 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
1eb60 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
1eb70 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
1eb80 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
1eb90 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
1eba0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
1ebb0 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
1ebc0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1ebd0 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
1ebe0 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
1ebf0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
1ec00 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
1ec10 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
1ec20 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
1ec30 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
1ec40 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1ec50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
1ec60 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
1ec70 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
1ec80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ec90 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
1eca0 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
1ecb0 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
1ecc0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
1ecd0 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
1ece0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
1ecf0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
1ed00 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
1ed10 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
1ed20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1ed30 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
1ed40 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1ed50 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
1ed60 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1ed70 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
1ed80 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
1ed90 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
1eda0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1edb0 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
1edc0 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
1edd0 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
1ede0 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
1edf0 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
1ee00 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1ee10 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
1ee20 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
1ee30 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
1ee40 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
1ee50 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
1ee60 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
1ee70 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
1ee80 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
1ee90 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
1eea0 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
1eeb0 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
1eec0 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
1eed0 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
1eee0 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
1eef0 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
1ef00 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
1ef10 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
1ef20 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
1ef30 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
1ef40 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
1ef50 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
1ef60 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
1ef70 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
1ef80 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
1ef90 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
1efa0 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
1efb0 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
1efc0 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
1efd0 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
1efe0 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
1eff0 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
1f000 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1f010 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
1f020 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
1f030 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
1f040 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
1f050 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
1f060 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
1f070 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
1f080 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
1f090 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
1f0a0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
1f0b0 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
1f0c0 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74  * ^On windows, t
1f0d0 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
1f0e0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
1f0f0 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
1f100 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
1f110 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
1f120 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
1f130 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
1f140 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
1f150 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
1f160 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
1f170 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
1f180 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
1f190 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
1f1a0 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
1f1b0 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
1f1c0 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
1f1d0 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
1f1e0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
1f1f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1f200 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1f210 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1f220 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
1f230 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
1f240 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1f250 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
1f260 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
1f270 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
1f280 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
1f290 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1f2a0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1f2b0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
1f2c0 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
1f2d0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
1f2e0 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
1f2f0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
1f300 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
1f310 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
1f320 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
1f330 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
1f340 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
1f350 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
1f360 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
1f370 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f380 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
1f390 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
1f3a0 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
1f3b0 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
1f3c0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
1f3d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
1f3e0 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
1f3f0 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
1f400 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
1f410 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
1f420 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f430 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
1f440 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
1f450 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
1f460 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
1f470 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
1f480 20 6f 72 0a 2a 2a 20 20 20 20 20 22 72 77 63 22   or.**     "rwc"
1f490 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
1f4a0 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
1f4b0 68 65 72 20 76 61 6c 75 65 20 69 73 20 61 6e 20  her value is an 
1f4c0 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
1f4d0 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
1f4e0 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
1f4f0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1f500 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
1f510 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
1f520 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
1f530 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1f540 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
1f550 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
1f560 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
1f570 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1f580 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2e  e3_prepare_v2().
1f590 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
1f5a0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
1f5b0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
1f5c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1f5d0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1f5e0 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
1f5f0 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
1f600 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
1f610 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1f620 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
1f630 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1f640 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
1f650 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
1f660 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
1f670 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
1f680 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
1f690 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1f6a0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
1f6b0 5f 43 52 45 41 54 45 2e 20 5e 49 66 20 73 71 6c  _CREATE. ^If sql
1f6c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1f6d0 73 20 0a 2a 2a 20 20 20 20 20 75 73 65 64 2c 20  s .**     used, 
1f6e0 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  it is an error t
1f6f0 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
1f700 65 20 66 6f 72 20 74 68 65 20 6d 6f 64 65 20 70  e for the mode p
1f710 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
1f720 20 0a 2a 2a 20 20 20 20 20 6c 65 73 73 20 72 65   .**     less re
1f730 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
1f740 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
1f750 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
1f760 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 0a  d as the third .
1f770 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
1f780 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
1f790 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
1f7a0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
1f7b0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
1f7c0 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
1f7d0 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
1f7e0 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
1f7f0 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
1f800 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1f810 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
1f820 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
1f830 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
1f840 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
1f850 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
1f860 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
1f870 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
1f880 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
1f890 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
1f8a0 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
1f8b0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1f8c0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
1f8d0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
1f8e0 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
1f8f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f900 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
1f910 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
1f920 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
1f930 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
1f940 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
1f950 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
1f960 62 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73  behaviour reques
1f970 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
1f980 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
1f990 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
1f9a0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
1f9b0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
1f9c0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
1f9d0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
1f9e0 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
1f9f0 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
1fa00 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
1fa10 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
1fa20 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
1fa30 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1fa40 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
1fa50 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
1fa60 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
1fa70 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
1fa80 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
1fa90 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
1faa0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
1fab0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
1fac0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
1fad0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
1fae0 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
1faf0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1fb00 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
1fb10 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
1fb20 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
1fb30 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
1fb40 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
1fb50 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
1fb60 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
1fb70 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
1fb80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
1fb90 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
1fba0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
1fbb0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
1fbc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
1fbd0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1fbe0 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
1fbf0 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
1fc00 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
1fc10 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
1fc20 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
1fc30 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1fc40 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
1fc50 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1fc60 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1fc70 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
1fc80 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
1fc90 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
1fca0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
1fcb0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
1fcc0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
1fcd0 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
1fce0 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
1fcf0 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
1fd00 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
1fd10 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
1fd20 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
1fd30 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
1fd40 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
1fd50 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
1fd60 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
1fd70 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
1fd80 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
1fd90 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
1fda0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
1fdb0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
1fdc0 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
1fdd0 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
1fde0 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
1fdf0 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
1fe00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
1fe10 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
1fe20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
1fe30 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
1fe40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1fe50 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
1fe60 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
1fe70 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
1fe80 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
1fe90 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
1fea0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
1feb0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
1fec0 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
1fed0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
1fee0 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
1fef0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1ff00 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1ff10 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
1ff20 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
1ff30 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
1ff40 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
1ff50 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
1ff60 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
1ff70 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
1ff80 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a  ix-nolock <td>.*
1ff90 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1ffa0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
1ffb0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
1ffc0 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
1ffd0 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a  unix-nolock"..**
1ffe0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1fff0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
20000 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
20010 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
20020 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
20030 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
20040 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
20050 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
20060 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
20070 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
20080 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
20090 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
200a0 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
200b0 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
200c0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
200d0 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
200e0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
200f0 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
20100 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
20110 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
20120 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
20130 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
20140 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
20150 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
20160 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
20170 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
20180 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
20190 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
201a0 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
201b0 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
201c0 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
201d0 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
201e0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
201f0 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
20200 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
20210 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
20220 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
20230 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
20240 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
20250 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
20260 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
20270 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
20280 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
20290 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
202a0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
202b0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
202c0 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
202d0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
202e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
202f0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
20300 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
20310 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
20320 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
20330 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
20340 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
20350 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
20360 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
20370 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
20380 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
20390 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
203a0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
203b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
203c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
203d0 29 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )..*/.SQLITE_API
203e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
203f0 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
20400 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
20410 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
20420 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
20430 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
20440 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
20450 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
20460 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
20470 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
20480 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
20490 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
204a0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
204b0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
204c0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
204d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
204e0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
204f0 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
20500 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
20510 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
20520 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
20530 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
20540 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
20550 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
20560 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
20570 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
20580 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
20590 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
205a0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
205b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
205c0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
205d0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
205e0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
205f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
20600 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
20610 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
20620 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
20630 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
20640 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
20650 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
20660 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
20670 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
20680 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
20690 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
206a0 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
206b0 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
206c0 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
206d0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
206e0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
206f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
20700 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
20710 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
20720 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
20730 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
20740 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
20750 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
20760 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
20770 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
20780 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
20790 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
207a0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
207b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
207c0 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
207d0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
207e0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
207f0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
20800 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
20810 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
20820 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
20830 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
20840 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
20850 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
20860 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
20870 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
20880 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
20890 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
208a0 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
208b0 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
208c0 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
208d0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
208e0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
208f0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
20900 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
20910 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
20920 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
20930 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
20940 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
20950 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
20960 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
20970 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
20980 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
20990 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
209a0 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
209b0 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
209c0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
209d0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
209e0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
209f0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
20a00 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
20a10 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
20a20 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
20a30 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
20a40 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
20a50 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
20a60 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
20a70 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
20a80 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
20a90 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
20aa0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
20ab0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
20ac0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
20ad0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
20ae0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
20af0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
20b00 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
20b10 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
20b20 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
20b30 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
20b40 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
20b50 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
20b60 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
20b70 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
20b80 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
20b90 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
20ba0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
20bb0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
20bc0 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
20bd0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
20be0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
20bf0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
20c00 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
20c10 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
20c20 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
20c30 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
20c40 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
20c50 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
20c60 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
20c70 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
20c80 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
20c90 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
20ca0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
20cb0 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
20cc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
20cd0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
20ce0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
20cf0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
20d00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
20d10 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
20d20 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
20d30 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
20d40 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
20d50 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
20d60 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
20d70 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
20d80 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
20d90 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
20da0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
20db0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
20dc0 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
20dd0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
20de0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
20df0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
20e00 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
20e10 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
20e20 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
20e30 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
20e40 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51  har *zParam);.SQ
20e50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
20e60 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
20e70 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
20e80 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
20e90 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
20ea0 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ault);.SQLITE_AP
20eb0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
20ec0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
20ed0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
20ee0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
20ef0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
20f00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
20f10 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
20f20 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
20f30 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
20f40 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
20f50 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
20f60 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
20f70 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
20f80 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
20f90 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
20fa0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
20fb0 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
20fc0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
20fd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20fe0 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
20ff0 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
21000 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
21010 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
21020 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
21030 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
21040 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
21050 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
21060 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
21070 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
21080 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
21090 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
210a0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
210b0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
210c0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
210d0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
210e0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
210f0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
21100 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
21110 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
21120 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
21130 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
21140 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
21150 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
21160 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
21170 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
21180 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
21190 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
211a0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
211b0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
211c0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
211d0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
211e0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
211f0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
21200 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
21210 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
21220 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
21230 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
21240 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
21250 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
21260 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
21270 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
21280 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
21290 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
212a0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
212b0 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
212c0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
212d0 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
212e0 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
212f0 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
21300 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
21310 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
21320 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
21330 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
21340 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
21350 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
21360 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
21370 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
21380 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
21390 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
213a0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
213b0 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
213c0 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
213d0 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
213e0 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
213f0 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
21400 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
21410 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
21420 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
21430 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21440 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
21450 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
21460 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
21470 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
21480 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
21490 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
214a0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
214b0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
214c0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
214d0 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
214e0 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
214f0 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
21500 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
21510 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
21520 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
21530 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
21540 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
21550 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
21560 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
21570 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
21580 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
21590 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
215a0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
215b0 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
215c0 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
215d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
215e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
215f0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
21600 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
21610 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
21620 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
21630 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
21640 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
21650 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
21660 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
21670 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
21680 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
21690 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
216a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
216b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
216c0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
216d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
216e0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
216f0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
21700 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
21710 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
21720 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
21730 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
21740 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
21750 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
21760 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
21770 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
21780 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
21790 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
217a0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
217b0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
217c0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
217d0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
217e0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
217f0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
21800 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
21810 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
21820 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21830 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
21840 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
21850 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
21860 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
21870 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
21880 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
21890 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
218a0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
218b0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
218c0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
218d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
218e0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
218f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
21900 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
21910 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
21920 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
21930 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
21940 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
21950 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
21960 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
21970 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
21980 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
21990 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
219a0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
219b0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
219c0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
219d0 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
219e0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
219f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
21a00 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
21a10 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
21a20 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
21a30 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
21a40 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
21a50 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
21a60 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
21a70 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
21a80 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
21a90 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
21aa0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
21ab0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
21ac0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
21ad0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
21ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21af0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
21b00 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
21b10 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
21b20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
21b30 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
21b40 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
21b50 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
21b60 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
21b70 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
21b80 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
21b90 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
21ba0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
21bb0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
21bc0 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
21bd0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
21be0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
21bf0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
21c00 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
21c10 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
21c20 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
21c30 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
21c40 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
21c50 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
21c60 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
21c70 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
21c80 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
21c90 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
21ca0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
21cb0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
21cc0 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
21cd0 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
21ce0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
21cf0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
21d00 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
21d10 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
21d20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
21d30 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
21d40 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
21d50 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
21d60 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
21d70 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
21d80 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
21d90 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
21da0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
21db0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
21dc0 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
21dd0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
21de0 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
21df0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
21e00 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
21e10 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
21e20 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
21e30 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
21e40 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
21e50 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
21e60 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
21e70 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
21e80 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
21e90 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
21ea0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
21eb0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
21ec0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
21ed0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
21ee0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
21ef0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
21f00 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
21f10 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
21f20 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
21f30 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
21f40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
21f50 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
21f60 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
21f70 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
21f80 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
21f90 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
21fa0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
21fb0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
21fc0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
21fd0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
21fe0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
21ff0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
22000 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
22010 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
22020 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
22030 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
22040 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
22050 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
22060 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
22070 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
22080 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
22090 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
220a0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
220b0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
220c0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
220d0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
220e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
220f0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
22100 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
22110 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
22120 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
22130 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
22140 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
22150 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
22160 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
22170 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
22180 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
22190 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
221a0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
221b0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
221c0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
221d0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
221e0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
221f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d   int sqlite3_lim
22200 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
22210 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
22220 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22230 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
22240 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
22250 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
22260 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
22270 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
22280 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
22290 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
222a0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
222b0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
222c0 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
222d0 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
222e0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
222f0 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
22300 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
22310 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
22320 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
22330 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
22340 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
22350 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
22360 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
22370 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
22380 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
22390 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
223a0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
223b0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
223c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
223d0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
223e0 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
223f0 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
22400 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
22410 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
22420 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
22430 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
22440 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
22450 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22460 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
22470 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
22480 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
22490 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
224a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
224b0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
224c0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
224d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
224e0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
224f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
22500 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
22510 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
22520 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
22530 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
22540 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
22550 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
22560 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
22570 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
22580 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
22590 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
225a0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
225b0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
225c0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
225d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
225e0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
225f0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
22600 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
22610 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
22620 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22630 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
22640 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
22650 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
22660 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
22670 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
22680 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
22690 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
226a0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
226b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
226c0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
226d0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
226e0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
226f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
22700 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
22710 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
22720 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
22730 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
22740 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
22750 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
22760 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
22770 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
22780 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
22790 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
227a0 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
227b0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
227c0 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
227d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
227e0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
227f0 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
22800 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
22810 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
22820 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
22830 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
22840 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
22850 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22860 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
22870 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
22880 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
22890 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
228a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
228b0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
228c0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
228d0 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
228e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
228f0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
22900 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
22910 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
22920 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
22930 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22940 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
22950 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
22960 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
22970 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
22980 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
22990 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
229a0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
229b0 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
229c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
229d0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
229e0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
229f0 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
22a00 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
22a10 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
22a20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
22a30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
22a40 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
22a50 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
22a60 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
22a70 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
22a80 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
22a90 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
22aa0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
22ab0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
22ac0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22ad0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
22ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22af0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
22b00 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
22b10 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
22b20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
22b30 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
22b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22b50 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
22b60 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
22b70 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
22b80 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
22b90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
22ba0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
22bb0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
22bc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
22bd0 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
22be0 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
22bf0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
22c00 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
22c10 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
22c20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
22c30 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
22c40 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
22c50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22c60 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
22c70 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
22c80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22c90 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
22ca0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
22cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22cc0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
22cd0 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
22ce0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
22cf0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
22d00 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
22d10 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
22d20 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
22d30 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
22d40 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
22d50 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
22d60 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
22d70 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
22d80 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
22d90 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
22da0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
22db0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
22dc0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
22dd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
22de0 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
22df0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
22e00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
22e10 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
22e20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
22e30 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
22e40 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
22e50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22e60 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
22e70 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
22e80 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
22e90 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
22ea0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
22eb0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
22ec0 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
22ed0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
22ee0 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
22ef0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
22f00 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
22f10 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
22f20 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
22f30 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
22f40 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
22f50 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22f60 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
22f70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
22f80 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
22f90 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
22fa0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
22fb0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
22fc0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
22fd0 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
22fe0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
22ff0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
23000 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
23010 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
23020 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
23030 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
23040 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
23050 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
23060 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
23070 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
23080 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
23090 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
230a0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
230b0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
230c0 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
230d0 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
230e0 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
230f0 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
23100 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
23110 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
23120 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
23130 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
23140 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
23150 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
23160 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
23170 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
23180 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
23190 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
231a0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
231b0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
231c0 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68  ator bytes as th
231d0 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20  is saves SQLite 
231e0 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a  from having to.*
231f0 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  * make a copy of
23200 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
23210 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  g..**.** ^If pzT
23220 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
23230 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
23240 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
23250 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
23260 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
23270 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
23280 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
23290 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
232a0 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
232b0 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
232c0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
232d0 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
232e0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
232f0 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
23300 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
23310 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
23320 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
23330 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
23340 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
23350 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
23360 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
23370 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
23380 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
23390 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
233a0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
233b0 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
233c0 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
233d0 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
233e0 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
233f0 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
23400 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
23410 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
23420 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
23430 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
23440 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
23450 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
23460 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
23470 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
23480 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
23490 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
234a0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
234b0 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
234c0 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
234d0 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
234e0 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
234f0 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
23500 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
23510 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
23520 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
23530 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
23540 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
23550 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
23560 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
23570 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
23580 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
23590 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
235a0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
235b0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
235c0 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
235d0 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
235e0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
235f0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
23600 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
23610 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
23620 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
23630 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
23640 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
23650 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
23660 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
23670 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
23680 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
23690 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
236a0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
236b0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
236c0 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
236d0 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
236e0 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
236f0 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
23700 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
23710 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
23720 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
23730 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
23740 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
23750 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
23760 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
23770 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
23780 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
23790 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
237a0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
237b0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
237c0 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a  o run it again..
237d0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
237e0 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
237f0 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
23800 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
23810 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
23820 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
23830 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
23840 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
23850 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
23860 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
23870 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
23880 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
23890 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
238a0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
238b0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
238c0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
238d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
238e0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
238f0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
23900 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23910 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
23920 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
23930 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
23940 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
23950 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
23960 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
23970 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
23980 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
23990 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
239a0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
239b0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
239c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
239d0 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
239e0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
239f0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
23a00 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
23a10 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
23a20 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
23a30 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
23a40 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
23a50 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
23a60 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
23a70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
23a80 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
23a90 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
23aa0 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
23ab0 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
23ac0 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
23ad0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
23ae0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
23af0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
23b00 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
23b10 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
23b20 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
23b30 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
23b40 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
23b50 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
23b60 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
23b70 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
23b80 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
23b90 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
23ba0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
23bb0 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
23bc0 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
23bd0 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
23be0 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
23bf0 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
23c00 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
23c10 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
23c20 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
23c30 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
23c40 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74  is enabled..** t
23c50 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  he .** </li>.** 
23c60 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ol>.*/.SQLITE_
23c70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
23c80 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
23c90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
23ca0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
23cb0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
23cc0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
23cd0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
23ce0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
23cf0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
23d00 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
23d10 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
23d20 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
23d30 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
23d40 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
23d50 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
23d60 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
23d70 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
23d80 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
23d90 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
23da0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
23db0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
23dc0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
23dd0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
23de0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
23df0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
23e00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
23e10 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
23e20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
23e30 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
23e40 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
23e50 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
23e60 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
23e70 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
23e80 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
23e90 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
23ea0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
23eb0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
23ec0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
23ed0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
23ee0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
23ef0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
23f00 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
23f10 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
23f20 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
23f30 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
23f40 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
23f50 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
23f60 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
23f70 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
23f80 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
23f90 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
23fa0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
23fb0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
23fc0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
23fd0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
23fe0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
23ff0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
24000 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
24010 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
24020 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
24030 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
24040 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
24050 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
24060 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24070 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
24080 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
24090 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
240a0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
240b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
240c0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
240d0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
240e0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
240f0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
24100 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
24110 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
24120 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
24130 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
24140 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
24150 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
24160 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
24170 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
24180 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
24190 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
241a0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
241b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
241c0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
241d0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
241e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
241f0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
24200 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
24210 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
24220 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
24230 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
24240 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24250 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
24260 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
24270 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
24280 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
24290 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
242a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
242b0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
242c0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
242d0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
242e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
242f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24300 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
24310 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
24320 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
24330 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
24340 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
24350 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
24360 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
24370 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
24380 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
24390 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
243a0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
243b0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
243c0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
243d0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
243e0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
243f0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
24400 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
24410 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
24420 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
24430 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
24440 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
24450 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
24460 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
24470 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
24480 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
24490 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
244a0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
244b0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
244c0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
244d0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
244e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
244f0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
24500 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
24510 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
24520 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
24530 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
24540 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
24550 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
24560 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
24570 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
24580 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
24590 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
245a0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
245b0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
245c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
245d0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
245e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
245f0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
24600 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
24610 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
24620 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
24630 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
24640 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
24650 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
24660 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
24670 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
24680 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
24690 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
246a0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
246b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
246c0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
246d0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
246e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
246f0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
24700 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
24710 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
24720 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
24730 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
24740 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
24750 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
24760 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
24770 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
24780 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
24790 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
247a0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
247b0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
247c0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
247d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
247e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
247f0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
24800 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
24810 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
24820 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
24830 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
24840 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
24850 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
24860 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
24870 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
24880 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24890 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
248a0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
248b0 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
248c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
248d0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
248e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
248f0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
24900 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
24910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24920 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
24930 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
24940 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
24950 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
24960 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
24970 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
24980 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
24990 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
249a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
249b0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
249c0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
249d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
249e0 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
249f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
24a00 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
24a10 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
24a20 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
24a30 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
24a40 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
24a50 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
24a60 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
24a70 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
24a80 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
24a90 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
24aa0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
24ab0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
24ac0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
24ad0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
24ae0 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
24af0 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
24b00 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
24b10 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
24b20 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
24b30 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
24b40 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
24b50 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
24b60 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
24b70 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
24b80 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
24b90 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
24ba0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
24bb0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
24bc0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
24bd0 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45   open..*/.SQLITE
24be0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
24bf0 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
24c00 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
24c10 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
24c20 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
24c30 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
24c40 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
24c50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
24c60 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
24c70 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
24c80 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
24c90 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
24ca0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
24cb0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
24cc0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
24cd0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
24ce0 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
24cf0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
24d00 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
24d10 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
24d20 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
24d30 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
24d40 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
24d50 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
24d60 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
24d70 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
24d80 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
24d90 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
24da0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
24db0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
24dc0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
24dd0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
24de0 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
24df0 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
24e00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
24e10 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
24e20 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
24e30 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
24e40 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
24e50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24e60 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
24e70 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
24e80 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
24e90 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
24ea0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
24eb0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
24ec0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
24ed0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
24ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
24ef0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
24f00 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
24f10 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
24f20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
24f30 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
24f40 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
24f50 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
24f60 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
24f70 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
24f80 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
24f90 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
24fa0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
24fb0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
24fc0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
24fd0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
24fe0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
24ff0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
25000 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
25010 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
25020 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
25030 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
25040 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
25050 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
25060 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
25070 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
25080 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
25090 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
250a0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
250b0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
250c0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
250d0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
250e0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
250f0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
25100 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
25110 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
25120 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
25130 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
25140 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
25150 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
25160 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
25170 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
25180 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
25190 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
251a0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
251b0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
251c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
251d0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
251e0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
251f0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
25200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25210 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
25220 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
25230 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
25240 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25250 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
25260 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
25270 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
25280 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
25290 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
252a0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
252b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
252c0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
252d0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
252e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
252f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
25300 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
25310 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
25320 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
25330 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
25340 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
25350 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
25360 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
25370 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
25380 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
25390 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
253a0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
253b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
253c0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
253d0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
253e0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
253f0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
25400 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
25410 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
25420 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
25430 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
25440 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
25450 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
25460 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
25470 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
25480 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
25490 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
254a0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
254b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
254c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
254d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
254e0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
254f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
25500 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
25510 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
25520 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
25530 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
25540 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
25550 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
25560 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
25570 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
25580 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
25590 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
255a0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
255b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
255c0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
255d0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
255e0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
255f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
25600 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
25610 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
25620 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
25630 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
25640 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
25650 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
25660 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
25670 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
25680 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
25690 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
256a0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
256b0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
256c0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
256d0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
256e0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
256f0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
25700 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
25710 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
25720 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
25730 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
25740 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
25750 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
25760 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
25770 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
25780 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
25790 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
257a0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
257b0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
257c0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
257d0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
257e0 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
257f0 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
25800 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
25810 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
25820 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
25830 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
25840 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
25850 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
25860 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
25870 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
25880 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
25890 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
258a0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
258b0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
258c0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
258d0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
258e0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
258f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
25900 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
25910 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
25920 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
25930 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
25940 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
25950 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
25960 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
25970 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
25980 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
25990 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
259a0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
259b0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
259c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
259d0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
259e0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
259f0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
25a00 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
25a10 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
25a20 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
25a30 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
25a40 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
25a50 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
25a60 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
25a70 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
25a80 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
25a90 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
25aa0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
25ab0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
25ac0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
25ad0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
25ae0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
25af0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
25b00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25b10 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25b20 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
25b30 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
25b40 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
25b50 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
25b60 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
25b70 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
25b80 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
25b90 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
25ba0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
25bb0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
25bc0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
25bd0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
25be0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
25bf0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
25c00 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
25c10 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
25c20 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
25c30 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
25c40 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
25c50 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
25c60 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
25c70 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
25c80 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
25c90 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
25ca0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
25cb0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
25cc0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
25cd0 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
25ce0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
25cf0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
25d00 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
25d10 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
25d20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
25d30 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
25d40 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
25d50 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
25d60 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
25d70 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
25d80 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
25d90 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
25da0 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
25db0 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
25dc0 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
25dd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
25de0 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
25df0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
25e00 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
25e10 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
25e20 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
25e30 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
25e40 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
25e50 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
25e60 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
25e70 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
25e80 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
25e90 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
25ea0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
25eb0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
25ec0 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
25ed0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
25ee0 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
25ef0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
25f00 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
25f10 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
25f20 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
25f30 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
25f40 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
25f50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
25f60 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
25f70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25f80 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
25f90 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
25fa0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
25fb0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
25fc0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
25fd0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
25fe0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
25ff0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
26000 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
26010 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
26020 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
26030 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
26040 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
26050 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
26060 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
26070 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
26080 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
26090 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
260a0 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
260b0 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
260c0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
260d0 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
260e0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
260f0 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
26100 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
26110 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
26120 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
26130 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
26140 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
26150 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
26160 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
26170 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
26180 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
26190 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
261a0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
261b0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
261c0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
261d0 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
261e0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
261f0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
26200 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
26210 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26220 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
26230 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
26240 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
26250 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
26260 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
26270 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
26280 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
26290 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
262a0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
262b0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
262c0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
262d0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
262e0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
262f0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
26300 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
26310 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
26320 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
26330 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
26340 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
26350 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
26360 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
26370 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
26380 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
26390 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
263a0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
263b0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
263c0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
263d0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
263e0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
263f0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
26400 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
26410 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
26420 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26430 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
26440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
26450 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
26460 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
26470 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
26480 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
26490 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
264a0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
264b0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
264c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
264d0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
264e0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
264f0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
26500 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26510 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
26520 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
26530 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
26540 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
26550 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
26560 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
26570 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
26580 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
26590 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
265a0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
265b0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
265c0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
265d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
265e0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
265f0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
26600 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
26610 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
26620 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
26630 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
26640 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
26650 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
26660 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
26670 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
26680 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
26690 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
266a0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
266b0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
266c0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
266d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
266e0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
266f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26700 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
26710 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
26720 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
26730 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
26740 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
26750 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
26760 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
26770 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
26780 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
26790 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
267a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
267b0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
267c0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
267d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
267e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
267f0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
26800 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49   int, int);.SQLI
26810 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26820 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
26830 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26840 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
26850 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26860 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
26870 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
26880 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
26890 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
268a0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
268b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
268c0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
268d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
268e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
268f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
26900 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
26910 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
26920 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
26930 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
26940 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26950 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
26960 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26970 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
26980 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
26990 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
269a0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
269b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
269c0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
269d0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
269e0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
269f0 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
26a00 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
26a10 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
26a20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
26a30 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
26a40 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
26a50 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
26a60 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
26a70 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
26a80 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
26a90 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
26aa0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
26ab0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
26ac0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
26ad0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
26ae0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
26af0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
26b00 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
26b10 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
26b20 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
26b30 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
26b40 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
26b50 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
26b60 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
26b70 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
26b80 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
26b90 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
26ba0 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
26bb0 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
26bc0 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
26bd0 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
26be0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
26bf0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
26c00 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
26c10 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
26c20 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
26c30 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
26c40 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
26c50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
26c60 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
26c70 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
26c80 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
26c90 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
26ca0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26cb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26cc0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
26cd0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
26ce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
26cf0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
26d00 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
26d10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
26d20 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
26d30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
26d40 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
26d50 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
26d60 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
26d70 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26d80 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
26d90 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
26da0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
26db0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
26dc0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
26dd0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
26de0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
26df0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
26e00 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
26e10 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
26e20 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
26e30 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
26e40 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
26e50 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
26e60 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
26e70 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
26e80 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
26e90 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
26ea0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
26eb0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
26ec0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
26ed0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
26ee0 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
26ef0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
26f00 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
26f10 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
26f20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
26f30 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
26f40 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
26f50 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
26f60 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
26f70 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
26f80 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
26f90 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
26fa0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
26fb0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
26fc0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
26fd0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
26fe0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
26ff0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
27000 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
27010 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
27020 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
27030 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
27040 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
27050 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
27060 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
27070 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
27080 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
27090 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
270a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
270b0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
270c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
270d0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
270e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
270f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27100 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27110 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
27120 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
27130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
27140 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
27150 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
27160 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
27170 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
27180 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
27190 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
271a0 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
271b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
271c0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
271d0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
271e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
271f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
27200 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
27210 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
27220 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
27230 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
27240 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
27250 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
27260 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
27270 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
27280 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
27290 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
272a0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
272b0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
272c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
272d0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
272e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
272f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27300 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
27310 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
27320 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
27330 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
27340 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27350 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
27360 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
27370 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
27380 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
27390 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
273a0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
273b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
273c0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
273d0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
273e0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
273f0 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
27400 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
27410 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
27420 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
27430 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
27440 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
27450 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
27460 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
27470 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
27480 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
27490 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
274a0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
274b0 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ULL..*/.SQLITE_A
274c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
274d0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
274e0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
274f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
27500 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
27510 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
27520 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
27530 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
27540 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
27550 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
27560 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
27570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
27580 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
27590 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
275a0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
275b0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
275c0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
275d0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
275e0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
275f0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
27600 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
27610 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
27620 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
27630 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
27640 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
27650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27660 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
27670 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
27680 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
27690 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
276a0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
276b0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
276c0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
276d0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
276e0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
276f0 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
27700 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
27710 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
27720 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
27730 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
27740 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
27750 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
27760 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
27770 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
27780 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
27790 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
277a0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
277b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
277c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
277d0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
277e0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
277f0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
27800 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
27810 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
27820 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
27830 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
27840 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
27850 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
27860 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
27870 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
27880 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
27890 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
278a0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
278b0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
278c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
278d0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
278e0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
278f0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
27900 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
27910 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
27920 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
27930 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
27940 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
27950 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
27960 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
27970 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
27980 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
27990 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
279a0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
279b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
279c0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
279d0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
279e0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
279f0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
27a00 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
27a10 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
27a20 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
27a30 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
27a40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
27a50 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
27a60 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
27a70 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
27a80 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
27a90 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
27aa0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
27ab0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
27ac0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
27ad0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
27ae0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
27af0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
27b00 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
27b10 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
27b20 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
27b30 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
27b40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
27b50 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27b60 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
27b70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27b80 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
27b90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
27ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
27bb0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
27bc0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
27bd0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
27be0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
27bf0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
27c00 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
27c10 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
27c20 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
27c30 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
27c40 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
27c50 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
27c60 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
27c70 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
27c80 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
27c90 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
27ca0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
27cb0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
27cc0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
27cd0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
27ce0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
27cf0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
27d00 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
27d10 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
27d20 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
27d30 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
27d40 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
27d50 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
27d60 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
27d70 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
27d80 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
27d90 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
27da0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
27db0 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
27dc0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
27dd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27de0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
27df0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27e00 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
27e10 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
27e20 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
27e30 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
27e40 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
27e50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27e60 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
27e70 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
27e80 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
27e90 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
27ea0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
27eb0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
27ec0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
27ed0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
27ee0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
27ef0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
27f00 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
27f10 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
27f20 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
27f30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
27f40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
27f50 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
27f60 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27f70 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
27f80 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
27f90 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
27fa0 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
27fb0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
27fc0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
27fd0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
27fe0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
27ff0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
28000 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
28010 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
28020 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
28030 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
28040 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
28050 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
28060 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
28070 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
28080 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
28090 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
280a0 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
280b0 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
280c0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
280d0 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
280e0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
280f0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
28100 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
28110 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
28120 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
28130 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
28140 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
28150 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
28160 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
28170 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
28180 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
28190 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
281a0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
281b0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
281c0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
281d0 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
281e0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
281f0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
28200 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
28210 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
28220 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
28230 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
28240 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
28250 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
28260 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
28270 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
28280 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
28290 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
282a0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
282b0 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
282c0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
282d0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
282e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
282f0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
28300 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
28310 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
28320 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
28330 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
28340 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
28350 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
28360 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
28370 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
28380 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
28390 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
283a0 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
283b0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
283c0 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
283d0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
283e0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
283f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
28400 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
28410 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
28420 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
28430 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
28440 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28450 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
28460 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
28470 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
28480 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
28490 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
284a0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
284b0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
284c0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
284d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
284e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
284f0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
28500 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
28510 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
28520 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28530 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
28540 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28550 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
28560 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28570 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
28580 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
28590 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
285a0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
285b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
285c0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
285d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
285e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
285f0 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
28600 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
28610 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
28620 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
28630 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
28640 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
28650 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
28660 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
28670 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
28680 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
28690 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
286a0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
286b0 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
286c0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
286d0 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
286e0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
286f0 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
28700 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
28710 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
28720 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
28730 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
28740 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
28750 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
28760 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
28770 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
28780 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
28790 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
287a0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
287b0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
287c0 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
287d0 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
287e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
287f0 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
28800 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
28810 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
28820 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
28830 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
28840 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
28850 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
28860 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
28870 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
28880 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
28890 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
288a0 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
288b0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
288c0 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
288d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
288e0 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
288f0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
28900 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
28910 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
28920 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
28930 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
28940 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
28950 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
28960 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
28970 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
28980 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
28990 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
289a0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
289b0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
289c0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
289d0 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
289e0 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
289f0 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
28a00 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
28a10 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
28a20 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
28a30 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
28a40 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
28a50 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
28a60 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
28a70 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
28a80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28a90 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
28aa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
28ab0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
28ac0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
28ad0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
28ae0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
28af0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
28b00 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
28b10 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
28b20 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
28b30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28b40 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
28b50 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
28b60 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
28b70 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
28b80 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
28b90 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
28ba0 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
28bb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
28bc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
28bd0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
28be0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
28bf0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
28c00 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
28c10 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
28c20 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
28c30 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
28c40 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
28c50 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
28c60 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
28c70 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
28c80 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
28c90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
28ca0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
28cb0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
28cc0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
28cd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28ce0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28cf0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
28d00 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
28d10 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
28d20 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
28d30 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
28d40 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
28d50 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
28d60 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
28d70 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
28d80 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
28d90 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
28da0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
28db0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
28dc0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
28dd0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
28de0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
28df0 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
28e00 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
28e10 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
28e20 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
28e30 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
28e40 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
28e50 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
28e60 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
28e70 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
28e80 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
28e90 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
28ea0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
28eb0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
28ec0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
28ed0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
28ee0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
28ef0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
28f00 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
28f10 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
28f20 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
28f30 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
28f40 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
28f50 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
28f60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
28f70 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
28f80 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
28f90 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
28fa0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
28fb0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
28fc0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
28fd0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
28fe0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
28ff0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
29000 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
29010 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
29020 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
29030 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
29040 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
29050 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
29060 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
29070 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
29080 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
29090 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
290a0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
290b0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
290c0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
290d0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
290e0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
290f0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
29100 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
29110 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29120 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
29130 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
29140 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
29150 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
29160 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
29170 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
29180 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
29190 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
291a0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
291b0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
291c0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
291d0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
291e0 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
291f0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
29200 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
29210 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
29220 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
29230 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
29240 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
29250 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
29260 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
29270 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
29280 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
29290 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
292a0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
292b0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
292c0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
292d0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
292e0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
292f0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
29300 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
29310 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
29320 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
29330 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
29340 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
29350 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
29360 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
29370 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
29380 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
29390 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
293a0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
293b0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
293c0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
293d0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
293e0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
293f0 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
29400 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
29410 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
29420 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
29430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
29440 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
29450 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
29460 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
29470 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
29480 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
29490 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
294a0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
294b0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
294c0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
294d0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
294e0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
294f0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
29500 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
29510 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29520 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
29530 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
29540 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
29550 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
29560 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
29570 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
29580 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
29590 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
295a0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
295b0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
295c0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
295d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
295e0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
295f0 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
29600 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
29610 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
29620 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
29630 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
29640 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
29650 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
29660 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
29670 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
29680 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
29690 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
296a0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
296b0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
296c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
296d0 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
296e0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
296f0 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
29700 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
29710 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
29720 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29730 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
29740 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
29750 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
29760 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
29770 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
29780 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
29790 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
297a0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
297b0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
297c0 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
297d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
297e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
297f0 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
29800 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
29810 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
29820 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
29830 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
29840 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
29850 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
29860 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
29870 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
29880 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
29890 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
298a0 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
298b0 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
298c0 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
298d0 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
298e0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
298f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
29900 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
29910 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
29920 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
29930 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
29940 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
29950 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
29960 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
29970 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
29980 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
29990 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
299a0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
299b0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
299c0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
299d0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
299e0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
299f0 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
29a00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29a10 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
29a20 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
29a30 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
29a40 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
29a50 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
29a60 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
29a70 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
29a80 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
29a90 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
29aa0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
29ab0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
29ac0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
29ad0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
29ae0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
29af0 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
29b00 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
29b10 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
29b20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29b30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
29b40 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
29b50 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
29b60 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
29b70 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
29b80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29b90 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
29ba0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
29bb0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
29bc0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
29bd0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
29be0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
29bf0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
29c00 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
29c10 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
29c20 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ded..*/.SQLITE_A
29c30 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
29c40 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
29c50 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
29c60 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
29c70 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
29c80 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
29c90 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
29ca0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
29cb0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
29cc0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
29cd0 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
29ce0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
29cf0 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
29d00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29d10 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
29d20 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
29d30 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
29d40 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
29d50 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
29d60 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
29d70 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
29d80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
29d90 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
29da0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
29db0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
29dc0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
29dd0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
29de0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
29df0 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
29e00 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
29e10 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
29e20 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
29e30 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
29e40 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
29e50 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
29e60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
29e70 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
29e80 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
29e90 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
29ea0 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
29eb0 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
29ec0 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
29ed0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
29ee0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
29ef0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
29f00 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
29f10 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
29f20 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
29f30 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
29f40 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
29f50 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
29f60 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
29f70 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
29f80 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
29f90 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
29fa0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
29fb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29fc0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
29fd0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
29fe0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
29ff0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2a000 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a010 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
2a020 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
2a030 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
2a040 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
2a050 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
2a060 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
2a070 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
2a080 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
2a090 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
2a0a0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2a0b0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
2a0c0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
2a0d0 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
2a0e0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
2a0f0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
2a100 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
2a110 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2a120 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
2a130 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
2a140 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
2a150 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
2a160 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
2a170 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
2a180 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
2a190 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
2a1a0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
2a1b0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
2a1c0 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
2a1d0 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
2a1e0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2a1f0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
2a200 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
2a210 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
2a220 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
2a230 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
2a240 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
2a250 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
2a260 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
2a270 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
2a280 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2a290 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
2a2a0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
2a2b0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2a2c0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
2a2d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
2a2e0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
2a2f0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
2a300 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
2a310 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
2a320 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
2a330 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
2a340 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2a350 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2a360 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a370 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
2a380 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
2a390 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2a3a0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2a3b0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2a3c0 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2a3d0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2a3e0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2a3f0 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
2a400 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2a410 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2a420 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2a430 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2a440 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2a450 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2a460 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2a470 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2a480 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
2a490 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a4a0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2a4b0 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
2a4c0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
2a4d0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2a4e0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
2a4f0 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
2a500 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
2a510 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
2a520 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2a530 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2a540 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
2a550 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
2a560 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2a570 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2a580 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
2a590 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2a5a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2a5b0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
2a5c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a5d0 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2a5e0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2a5f0 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2a600 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2a610 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2a620 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2a630 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2a640 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a650 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2a660 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2a670 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2a680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2a690 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2a6a0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2a6b0 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2a6c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2a6d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2a6e0 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2a6f0 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2a700 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2a710 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2a720 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2a730 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2a740 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2a750 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2a760 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2a770 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2a780 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2a790 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2a7a0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2a7b0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2a7c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2a7d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a7e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2a7f0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2a800 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2a810 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2a820 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2a830 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2a840 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2a850 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2a860 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2a870 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2a880 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a890 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2a8a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2a8b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
2a8c0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2a8d0 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
2a8e0 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
2a8f0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
2a900 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
2a910 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
2a920 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2a930 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
2a940 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2a950 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
2a960 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
2a970 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
2a980 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
2a990 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2a9a0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2a9b0 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
2a9c0 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
2a9d0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
2a9e0 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
2a9f0 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
2aa00 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
2aa10 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
2aa20 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
2aa30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2aa40 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
2aa50 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
2aa60 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2aa70 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
2aa80 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2aa90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2aaa0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
2aab0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2aac0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
2aad0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2aae0 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
2aaf0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2ab00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ab10 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2ab20 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2ab30 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2ab40 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2ab50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2ab60 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
2ab70 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2ab80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ab90 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
2aba0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2abb0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
2abc0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2abd0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2abe0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2abf0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2ac00 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2ac10 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2ac20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2ac30 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2ac40 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2ac50 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2ac60 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2ac70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2ac80 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2ac90 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2aca0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2acb0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2acc0 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
2acd0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
2ace0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2acf0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
2ad00 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2ad10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ad20 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
2ad30 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2ad40 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2ad50 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2ad60 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2ad70 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ad80 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
2ad90 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2ada0 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
2adb0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2adc0 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
2add0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2ade0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2adf0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2ae00 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2ae10 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2ae20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ae30 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
2ae40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2ae50 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2ae60 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2ae70 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
2ae80 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2ae90 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2aea0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2aeb0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2aec0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2aed0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2aee0 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
2aef0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
2af00 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2af10 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2af20 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2af30 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
2af40 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2af50 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
2af60 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2af70 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
2af80 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
2af90 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
2afa0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
2afb0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2afc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2afd0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2afe0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2aff0 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
2b000 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
2b010 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
2b020 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2b030 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
2b040 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
2b050 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2b060 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
2b070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b080 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
2b090 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
2b0a0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
2b0b0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
2b0c0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
2b0d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
2b0e0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
2b0f0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2b100 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
2b110 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2b120 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2b130 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2b140 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2b150 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2b160 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b170 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
2b180 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b190 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
2b1a0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
2b1b0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
2b1c0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
2b1d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
2b1e0 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
2b1f0 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
2b200 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b210 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
2b220 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2b230 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2b240 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
2b250 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
2b260 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
2b270 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
2b280 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
2b290 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
2b2a0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2b2b0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2b2c0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
2b2d0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2b2e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2b2f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2b300 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
2b310 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2b320 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
2b330 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
2b340 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
2b350 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
2b360 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
2b370 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
2b380 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
2b390 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2b3a0 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
2b3b0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
2b3c0 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
2b3d0 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
2b3e0 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
2b3f0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
2b400 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
2b410 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
2b420 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
2b430 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
2b440 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
2b450 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
2b460 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
2b470 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
2b480 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
2b490 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
2b4a0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2b4b0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2b4c0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
2b4d0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2b4e0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2b4f0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2b500 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
2b510 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2b520 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
2b530 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
2b540 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2b550 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2b560 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
2b570 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
2b580 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2b590 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2b5a0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2b5b0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
2b5c0 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
2b5d0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2b5e0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b5f0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2b600 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
2b610 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2b620 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2b630 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2b640 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
2b650 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2b660 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
2b670 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
2b680 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
2b690 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
2b6a0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2b6b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2b6c0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2b6d0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2b6e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2b6f0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2b700 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2b710 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
2b720 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2b730 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2b740 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
2b750 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2b760 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
2b770 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
2b780 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
2b790 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2b7a0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
2b7b0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
2b7c0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2b7d0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2b7e0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
2b7f0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
2b800 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2b810 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
2b820 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2b830 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
2b840 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
2b850 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2b860 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2b870 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
2b880 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
2b890 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
2b8a0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
2b8b0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
2b8c0 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
2b8d0 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
2b8e0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
2b8f0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
2b900 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
2b910 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
2b920 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
2b930 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
2b940 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
2b950 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
2b960 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
2b970 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
2b980 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
2b990 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
2b9a0 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
2b9b0 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
2b9c0 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
2b9d0 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
2b9e0 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
2b9f0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
2ba00 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
2ba10 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
2ba20 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
2ba30 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2ba40 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2ba50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ba60 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
2ba70 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2ba80 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
2ba90 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2baa0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
2bab0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
2bac0 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
2bad0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
2bae0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
2baf0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2bb00 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2bb10 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
2bb20 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
2bb30 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2bb40 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2bb50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2bb60 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
2bb70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
2bb80 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
2bb90 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
2bba0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
2bbb0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2bbc0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2bbd0 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
2bbe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bbf0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
2bc00 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2bc10 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2bc20 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2bc30 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2bc40 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2bc50 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
2bc60 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2bc70 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2bc80 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
2bc90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2bca0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
2bcb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bcc0 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
2bcd0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2bce0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2bcf0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
2bd00 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2bd10 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
2bd20 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
2bd30 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
2bd40 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
2bd50 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
2bd60 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
2bd70 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
2bd80 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
2bd90 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
2bda0 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
2bdb0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
2bdc0 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
2bdd0 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
2bde0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
2bdf0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
2be00 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
2be10 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
2be20 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
2be30 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
2be40 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
2be50 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
2be60 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
2be70 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
2be80 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
2be90 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
2bea0 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
2beb0 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
2bec0 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
2bed0 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
2bee0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
2bef0 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
2bf00 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
2bf10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2bf20 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2bf30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2bf40 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2bf50 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2bf60 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
2bf70 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2bf80 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2bf90 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2bfa0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2bfb0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2bfc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2bfd0 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
2bfe0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
2bff0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
2c000 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
2c010 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
2c020 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2c030 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
2c040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c050 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
2c060 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
2c070 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
2c080 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
2c090 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
2c0a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2c0b0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2c0c0 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
2c0d0 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
2c0e0 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
2c0f0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
2c100 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2c110 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
2c120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2c130 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
2c140 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2c150 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
2c160 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
2c170 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2c180 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
2c190 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
2c1a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c1b0 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
2c1c0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2c1d0 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
2c1e0 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
2c1f0 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
2c200 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
2c210 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
2c220 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2c230 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c240 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2c250 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
2c260 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
2c270 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
2c280 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
2c290 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
2c2a0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
2c2b0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
2c2c0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
2c2d0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
2c2e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2c2f0 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2c300 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c310 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2c320 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2c330 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
2c340 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2c350 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2c360 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
2c370 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
2c380 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2c390 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
2c3a0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2c3b0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
2c3c0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
2c3d0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
2c3e0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
2c3f0 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
2c400 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2c410 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
2c420 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2c430 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
2c440 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
2c450 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
2c460 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2c470 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2c480 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
2c490 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c4a0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2c4b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2c4c0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
2c4d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2c4e0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2c4f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2c500 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
2c510 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2c520 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  l);.SQLITE_API d
2c530 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2c540 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2c550 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c560 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2c570 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2c580 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2c590 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c5a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2c5b0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2c5c0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2c5d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c5e0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2c5f0 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
2c600 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2c610 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
2c620 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c630 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2c640 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2c650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c660 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2c670 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2c680 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2c690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2c6a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c6b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2c6c0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
2c6d0 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
2c6e0 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
2c6f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2c700 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
2c710 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
2c720 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2c730 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2c740 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2c750 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
2c760 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
2c770 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
2c780 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2c790 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2c7a0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2c7b0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2c7c0 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
2c7d0 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
2c7e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2c7f0 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
2c800 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
2c810 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
2c820 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
2c830 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
2c840 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2c850 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
2c860 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
2c870 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
2c880 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
2c890 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
2c8a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
2c8b0 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
2c8c0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2c8d0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2c8e0 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
2c8f0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
2c900 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
2c910 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
2c920 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
2c930 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
2c940 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
2c950 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
2c960 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
2c970 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
2c980 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2c990 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
2c9a0 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
2c9b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c9c0 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
2c9d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
2c9e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2c9f0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
2ca00 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
2ca10 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
2ca20 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
2ca30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2ca40 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
2ca50 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
2ca60 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
2ca70 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
2ca80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ca90 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
2caa0 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
2cab0 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
2cac0 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
2cad0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2cae0 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
2caf0 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
2cb00 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2cb10 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2cb20 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
2cb30 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
2cb40 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2cb50 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2cb60 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
2cb70 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
2cb80 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
2cb90 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
2cba0 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
2cbb0 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
2cbc0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2cbd0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
2cbe0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
2cbf0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2cc00 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2cc10 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2cc20 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2cc30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2cc40 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2cc50 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2cc60 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2cc70 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2cc80 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2cc90 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2cca0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2ccb0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
2ccc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2ccd0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2cce0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2ccf0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2cd00 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2cd10 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2cd20 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2cd30 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2cd40 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2cd50 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2cd60 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2cd70 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2cd80 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2cd90 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2cda0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2cdb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cdc0 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
2cdd0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2cde0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2cdf0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2ce00 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2ce10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2ce20 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2ce30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ce40 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2ce50 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2ce60 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2ce70 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2ce80 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2ce90 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2cea0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
2ceb0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2cec0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2ced0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2cee0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2cef0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2cf00 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2cf10 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2cf20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2cf30 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2cf40 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
2cf50 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2cf60 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2cf70 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2cf80 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2cf90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2cfa0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2cfb0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2cfc0 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
2cfd0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
2cfe0 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
2cff0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2d000 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2d010 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d020 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
2d030 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2d040 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d050 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
2d060 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
2d070 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
2d080 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
2d090 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
2d0a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2d0b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d0c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
2d0d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2d0e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d0f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
2d100 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
2d110 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
2d120 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
2d130 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2d140 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
2d150 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2d160 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2d170 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
2d180 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
2d190 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
2d1a0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
2d1b0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2d1c0 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
2d1d0 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
2d1e0 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
2d1f0 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
2d200 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
2d210 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
2d220 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
2d230 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2d240 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
2d250 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
2d260 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
2d270 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
2d280 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2d290 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
2d2a0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2d2b0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2d2c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2d2d0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
2d2e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2d2f0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
2d300 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
2d310 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
2d320 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
2d330 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
2d340 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2d350 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
2d360 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2d370 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
2d380 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
2d390 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
2d3a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
2d3b0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
2d3c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2d3d0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2d3e0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2d3f0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
2d400 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
2d410 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
2d420 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
2d430 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
2d440 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
2d450 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
2d460 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
2d470 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
2d480 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
2d490 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
2d4a0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
2d4b0 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
2d4c0 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
2d4d0 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
2d4e0 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
2d4f0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
2d500 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
2d510 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
2d520 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
2d530 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
2d540 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2d550 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
2d560 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
2d570 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2d580 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2d590 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2d5a0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2d5b0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
2d5c0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
2d5d0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
2d5e0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2d5f0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
2d600 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2d610 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
2d620 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
2d630 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
2d640 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
2d650 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2d660 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
2d670 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
2d680 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
2d690 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2d6a0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
2d6b0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
2d6c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2d6d0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
2d6e0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
2d6f0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
2d700 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
2d710 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
2d720 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
2d730 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
2d740 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
2d750 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63    Every SQL func
2d760 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2d770 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65  ion must be able
2d780 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
2d790 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
2d7a0 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
2d7b0 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
2d7c0 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
2d7d0 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
2d7e0 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
2d7f0 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
2d800 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
2d810 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
2d820 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2d830 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
2d840 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d850 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
2d860 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
2d870 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2d880 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
2d890 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
2d8a0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
2d8b0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
2d8c0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2d8d0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2d8e0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
2d8f0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
2d900 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
2d910 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
2d920 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
2d930 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
2d940 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
2d950 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
2d960 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
2d970 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
2d980 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
2d990 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
2d9a0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
2d9b0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
2d9c0 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
2d9d0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
2d9e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
2d9f0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
2da00 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
2da10 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
2da20 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
2da30 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
2da40 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
2da50 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2da60 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
2da70 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
2da80 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
2da90 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
2daa0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
2dab0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
2dac0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
2dad0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
2dae0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2daf0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2db00 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
2db10 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2db20 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2db30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2db40 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
2db50 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
2db60 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
2db70 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2db80 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
2db90 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
2dba0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
2dbb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2dbc0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2dbd0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
2dbe0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
2dbf0 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
2dc00 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
2dc10 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
2dc20 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
2dc30 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2dc40 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
2dc50 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
2dc60 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
2dc70 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
2dc80 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
2dc90 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
2dca0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2dcb0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2dcc0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
2dcd0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
2dce0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
2dcf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2dd00 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
2dd10 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
2dd20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
2dd30 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2dd40 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
2dd50 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
2dd60 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
2dd70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2dd80 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
2dd90 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
2dda0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
2ddb0 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
2ddc0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2ddd0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2dde0 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
2ddf0 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
2de00 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
2de10 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
2de20 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
2de30 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
2de40 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
2de50 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
2de60 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2de70 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
2de80 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
2de90 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
2dea0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
2deb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2dec0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
2ded0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
2dee0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
2def0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2df00 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
2df10 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
2df20 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
2df30 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
2df40 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
2df50 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
2df60 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
2df70 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2df80 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
2df90 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
2dfa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
2dfb0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
2dfc0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
2dfd0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
2dfe0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
2dff0 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
2e000 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2e010 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
2e020 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
2e030 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
2e040 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2e050 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e060 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
2e070 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
2e080 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
2e090 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
2e0a0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
2e0b0 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
2e0c0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2e0d0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
2e0e0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2e0f0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2e100 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2e110 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
2e120 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2e130 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2e140 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
2e150 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
2e160 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
2e170 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
2e180 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2e190 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2e1a0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
2e1b0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
2e1c0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
2e1d0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
2e1e0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
2e1f0 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
2e200 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2e210 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
2e220 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2e230 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
2e240 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
2e250 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
2e260 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
2e270 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
2e280 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
2e290 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
2e2a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
2e2b0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
2e2c0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2e2d0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2e2e0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
2e2f0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2e300 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2e310 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2e320 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
2e330 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2e340 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
2e350 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2e360 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2e370 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2e380 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2e390 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2e3a0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2e3b0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2e3c0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2e3d0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2e3e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2e3f0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2e400 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e410 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
2e420 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2e430 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
2e440 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2e450 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
2e460 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2e470 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2e480 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2e490 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2e4a0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2e4b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2e4c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2e4d0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2e4e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2e4f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2e500 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2e510 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2e520 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
2e530 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2e540 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e550 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2e560 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2e570 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2e580 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2e590 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2e5a0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2e5b0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2e5c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e5d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e5e0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2e5f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2e600 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2e610 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2e620 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2e630 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
2e640 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
2e650 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2e660 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
2e670 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
2e680 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
2e690 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
2e6a0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
2e6b0 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
2e6c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
2e6d0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
2e6e0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
2e6f0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
2e700 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2e710 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
2e720 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
2e730 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
2e740 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2e750 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
2e760 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
2e770 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2e780 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
2e790 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
2e7a0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
2e7b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e7c0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
2e7d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2e7e0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
2e7f0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2e800 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
2e810 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
2e820 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
2e830 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
2e840 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
2e850 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
2e860 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
2e870 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
2e880 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
2e890 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
2e8a0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
2e8b0 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
2e8c0 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
2e8d0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
2e8e0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
2e8f0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2e900 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
2e910 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
2e920 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
2e930 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
2e940 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
2e950 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
2e960 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
2e970 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
2e980 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
2e990 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
2e9a0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
2e9b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
2e9c0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2e9d0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
2e9e0 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
2e9f0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
2ea00 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
2ea10 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2ea20 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
2ea30 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
2ea40 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
2ea50 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2ea60 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
2ea70 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2ea80 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
2ea90 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
2eaa0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
2eab0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2eac0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
2ead0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
2eae0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2eaf0 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
2eb00 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
2eb10 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
2eb20 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2eb30 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2eb40 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2eb50 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2eb60 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2eb70 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2eb80 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
2eb90 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2eba0 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
2ebb0 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
2ebc0 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
2ebd0 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
2ebe0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
2ebf0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2ec00 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
2ec10 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
2ec20 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
2ec30 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
2ec40 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
2ec50 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
2ec60 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
2ec70 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
2ec80 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
2ec90 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
2eca0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
2ecb0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
2ecc0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ecd0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2ece0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ecf0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2ed00 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
2ed10 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
2ed20 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2ed30 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2ed40 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
2ed50 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
2ed60 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
2ed70 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2ed80 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
2ed90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2eda0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
2edb0 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
2edc0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2edd0 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
2ede0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
2edf0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
2ee00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2ee10 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
2ee20 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
2ee30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2ee40 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
2ee50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2ee60 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
2ee70 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2ee80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2ee90 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
2eea0 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
2eeb0 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
2eec0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2eed0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
2eee0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
2eef0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
2ef00 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
2ef10 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
2ef20 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
2ef30 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
2ef40 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2ef50 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
2ef60 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
2ef70 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
2ef80 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2ef90 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2efa0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
2efb0 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
2efc0 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
2efd0 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
2efe0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
2eff0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f000 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2f010 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
2f020 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
2f030 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
2f040 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
2f050 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
2f060 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
2f070 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f080 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
2f090 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2f0a0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
2f0b0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
2f0c0 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
2f0d0 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
2f0e0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
2f0f0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
2f100 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
2f110 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2f120 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2f130 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
2f140 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
2f150 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
2f160 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
2f170 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
2f180 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
2f190 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
2f1a0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
2f1b0 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
2f1c0 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
2f1d0 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
2f1e0 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
2f1f0 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
2f200 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
2f210 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
2f220 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
2f230 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
2f240 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
2f250 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2f260 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
2f270 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
2f280 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
2f290 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
2f2a0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
2f2b0 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
2f2c0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
2f2d0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2f2e0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2f2f0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2f300 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2f310 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2f320 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
2f330 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2f340 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2f350 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2f360 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2f370 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
2f380 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
2f390 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2f3a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2f3b0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
2f3c0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
2f3d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2f3e0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2f3f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f400 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
2f410 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2f420 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2f430 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2f440 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
2f450 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
2f460 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
2f470 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
2f480 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c  rameters..*/.SQL
2f490 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2f4a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2f4b0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
2f4c0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2f4d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
2f4e0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
2f4f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2f500 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2f510 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2f520 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f530 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
2f540 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
2f550 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
2f560 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2f570 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2f580 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
2f590 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2f5a0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
2f5b0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2f5c0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2f5d0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2f5e0 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
2f5f0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2f600 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
2f610 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2f620 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2f630 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2f640 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
2f650 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2f660 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2f670 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2f680 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2f690 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2f6a0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2f6b0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2f6c0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
2f6d0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2f6e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2f6f0 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
2f700 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2f710 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2f720 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2f730 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
2f740 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
2f750 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
2f760 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
2f770 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
2f780 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
2f790 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
2f7a0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
2f7b0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
2f7c0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
2f7d0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
2f7e0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
2f7f0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
2f800 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
2f810 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2f820 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
2f830 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
2f840 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
2f850 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
2f860 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
2f870 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
2f880 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
2f890 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2f8a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
2f8b0 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
2f8c0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
2f8d0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
2f8e0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2f8f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2f900 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
2f910 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
2f920 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
2f930 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
2f940 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
2f950 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
2f960 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
2f970 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
2f980 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
2f990 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
2f9a0 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
2f9b0 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
2f9c0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
2f9d0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
2f9e0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
2f9f0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
2fa00 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
2fa10 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
2fa20 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
2fa30 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
2fa40 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
2fa50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
2fa60 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
2fa70 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
2fa80 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
2fa90 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
2faa0 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
2fab0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2fac0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
2fad0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
2fae0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
2faf0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
2fb00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fb10 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2fb20 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
2fb30 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
2fb40 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69  L pointer if N i
2fb50 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f  s.** less than o
2fb60 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
2fb70 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  or if a memory a
2fb80 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
2fb90 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
2fba0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
2fbb0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
2fbc0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2fbd0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
2fbe0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
2fbf0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
2fc00 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
2fc10 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
2fc20 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
2fc30 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
2fc40 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2fc50 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2fc60 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
2fc70 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
2fc80 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2fc90 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
2fca0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
2fcb0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
2fcc0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  n.)^.**.** ^SQLi
2fcd0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2fce0 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
2fcf0 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
2fd00 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2fd10 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
2fd20 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
2fd30 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
2fd40 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
2fd50 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
2fd60 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
2fd70 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
2fd80 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
2fd90 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
2fda0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
2fdb0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
2fdc0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
2fdd0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
2fde0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
2fdf0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
2fe00 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
2fe10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2fe20 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2fe30 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2fe40 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2fe50 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
2fe60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2fe70 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
2fe80 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
2fe90 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2fea0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
2feb0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
2fec0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
2fed0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
2fee0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
2fef0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ff00 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
2ff10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ff20 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2ff30 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
2ff40 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
2ff50 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
2ff60 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
2ff70 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
2ff80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ff90 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
2ffa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ffb0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
2ffc0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
2ffd0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
2ffe0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2fff0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
30000 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
30010 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
30020 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
30030 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
30040 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
30050 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30060 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
30070 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
30080 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
30090 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
300a0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
300b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
300c0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
300d0 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
300e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
300f0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
30100 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
30110 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
30120 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
30130 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
30140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
30150 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
30160 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
30170 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30180 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
30190 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
301a0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
301b0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
301c0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
301d0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
301e0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
301f0 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ction..*/.SQLITE
30200 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71  _API sqlite3 *sq
30210 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
30220 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
30230 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
30240 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
30250 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
30260 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ata.**.** The fo
30270 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
30280 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
30290 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
302a0 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
302b0 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
302c0 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
302d0 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
302e0 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
302f0 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
30300 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
30310 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
30320 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
30330 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
30340 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
30350 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
30360 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
30370 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
30380 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
30390 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
303a0 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
303b0 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
303c0 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
303d0 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
303e0 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
303f0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
30400 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
30410 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
30420 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
30430 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
30440 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
30450 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
30460 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
30470 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
30480 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
30490 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
304a0 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
304b0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
304c0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
304d0 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
304e0 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
304f0 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
30500 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
30510 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
30520 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
30530 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30540 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
30550 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30560 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30570 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
30580 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
30590 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
305a0 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
305b0 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
305c0 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
305d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
305e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
305f0 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61  n. ^If no metada
30600 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72  ta has been ever
30610 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72  .** been set for
30620 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
30630 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  t of the functio
30640 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72  n, or if the cor
30650 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75  responding.** fu
30660 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
30670 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e   has changed sin
30680 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ce the meta-data
30690 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65   was set,.** the
306a0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
306b0 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20  xdata() returns 
306c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
306d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
306e0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
306f0 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
30700 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
30710 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
30720 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
30730 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
30740 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
30750 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
30760 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30770 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
30780 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
30790 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
307a0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
307b0 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
307c0 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
307d0 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
307e0 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  oyed..** ^If it 
307f0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
30800 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
30810 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
30820 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
30830 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
30840 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30850 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
30860 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74  n.** the metadat
30870 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
30880 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
30890 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
308a0 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
308b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
308c0 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
308d0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
308e0 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
308f0 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
30900 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
30910 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61  nd drop metadata
30920 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d   on any.** param
30930 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63  eter of any func
30940 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65  tion at any time
30950 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61  .  ^The only gua
30960 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
30970 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
30980 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
30990 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
309a0 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
309b0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
309c0 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
309d0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
309e0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
309f0 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
30a00 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
30a10 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
30a20 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
30a30 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
30a40 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
30a50 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a  ameters].)^.**.*
30a60 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
30a70 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
30a80 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
30a90 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
30aa0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30ab0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
30ac0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
30ad0 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
30ae0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
30af0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
30b00 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
30b10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
30b20 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
30b30 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
30b40 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
30b50 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
30b60 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
30b70 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
30b80 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
30b90 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
30ba0 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
30bb0 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
30bc0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
30bd0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
30be0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
30bf0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
30c00 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
30c10 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
30c20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
30c30 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
30c40 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
30c50 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
30c60 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
30c70 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
30c80 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
30c90 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
30ca0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
30cb0 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
30cc0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
30cd0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
30ce0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
30cf0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
30d00 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
30d10 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
30d20 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
30d30 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
30d40 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
30d50 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
30d60 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
30d70 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
30d80 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
30d90 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
30da0 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
30db0 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
30dc0 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
30dd0 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
30de0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
30df0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
30e00 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
30e10 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
30e20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
30e30 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
30e40 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
30e50 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
30e60 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
30e70 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
30e80 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
30e90 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
30ea0 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
30eb0 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
30ec0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
30ed0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
30ee0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
30ef0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
30f00 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
30f10 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
30f20 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
30f30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30f40 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
30f50 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30f60 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
30f70 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
30f80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
30f90 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
30fa0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
30fb0 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
30fc0 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
30fd0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
30fe0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
30ff0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
31000 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
31010 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
31020 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
31030 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
31040 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
31050 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
31060 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
31070 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31080 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
31090 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
310a0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
310b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
310c0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
310d0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
310e0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
310f0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
31100 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
31110 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
31120 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
31130 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
31140 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
31150 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31160 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
31170 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
31180 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
31190 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
311a0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
311b0 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
311c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
311d0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
311e0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
311f0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
31200 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
31210 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
31220 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31230 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
31240 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
31250 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
31260 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
31270 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31280 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
31290 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
312a0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
312b0 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
312c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
312d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
312e0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
312f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31300 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
31310 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
31320 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
31330 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
31340 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
31350 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
31360 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
31370 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
31380 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
31390 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
313a0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
313b0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
313c0 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
313d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
313e0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
313f0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
31400 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
31410 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
31420 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
31430 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
31440 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
31450 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
31460 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31470 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
31480 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
31490 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
314a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
314b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
314c0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
314d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
314e0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
314f0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
31500 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
31510 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
31520 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
31530 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
31540 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
31550 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
31560 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
31570 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31580 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
31590 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
315a0 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
315b0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
315c0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
315d0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
315e0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
315f0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
31600 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
31610 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
31620 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31630 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
31640 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31650 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
31660 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
31670 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
31680 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
31690 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
316a0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
316b0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
316c0 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
316d0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
316e0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
316f0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
31700 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
31710 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31720 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
31730 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
31740 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
31750 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
31760 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
31770 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
31780 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
31790 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
317a0 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
317b0 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
317c0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
317d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
317e0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
317f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31800 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
31810 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
31820 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
31830 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31840 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
31850 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
31860 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
31870 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
31880 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
31890 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
318a0 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
318b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
318c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
318d0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
318e0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
318f0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
31900 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
31910 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
31920 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
31930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31940 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
31950 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
31960 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
31970 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
31980 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31990 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
319a0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
319b0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
319c0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
319d0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
319e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
319f0 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
31a00 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
31a10 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
31a20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
31a30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31a40 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
31a50 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
31a60 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
31a70 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
31a80 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
31a90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
31aa0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
31ab0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
31ac0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
31ad0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31ae0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31af0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
31b00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31b10 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
31b20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31b30 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
31b40 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
31b50 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
31b60 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
31b70 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
31b80 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
31b90 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
31ba0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31bb0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
31bc0 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
31bd0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
31be0 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
31bf0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
31c00 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
31c10 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
31c20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
31c30 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
31c40 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
31c50 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
31c60 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
31c70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
31c80 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
31c90 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
31ca0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31cb0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
31cc0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
31cd0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
31ce0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
31cf0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
31d00 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
31d10 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
31d20 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
31d30 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
31d40 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
31d50 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
31d60 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
31d70 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
31d80 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
31d90 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
31da0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
31db0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
31dc0 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
31dd0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
31de0 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
31df0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
31e00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
31e10 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
31e20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31e30 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
31e40 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
31e50 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
31e60 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
31e70 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
31e80 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
31e90 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
31ea0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
31eb0 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
31ec0 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
31ed0 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
31ee0 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
31ef0 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
31f00 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
31f10 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
31f20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
31f30 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
31f40 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
31f50 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
31f60 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
31f70 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
31f80 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
31f90 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
31fa0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
31fb0 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
31fc0 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
31fd0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
31fe0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
31ff0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
32000 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
32010 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32020 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
32030 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
32040 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
32050 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
32060 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
32070 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
32080 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
32090 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
320a0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
320b0 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
320c0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
320d0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
320e0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
320f0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
32100 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
32110 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
32120 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
32130 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
32140 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
32150 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
32160 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
32170 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
32180 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
32190 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
321a0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
321b0 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
321c0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
321d0 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
321e0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
321f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
32200 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
32210 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
32220 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
32230 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
32240 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
32250 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
32260 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
32270 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
32280 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
32290 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
322a0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
322b0 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
322c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
322d0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
322e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
322f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
32300 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
32310 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
32320 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32330 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
32340 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
32350 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
32360 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32370 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
32380 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
32390 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
323a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
323b0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
323c0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
323d0 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
323e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
323f0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
32400 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
32410 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
32420 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
32430 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
32440 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
32450 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
32460 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
32470 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
32480 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
32490 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
324a0 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
324b0 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
324c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
324d0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
324e0 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
324f0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
32500 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32510 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
32520 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
32530 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
32540 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32550 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
32560 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
32570 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
32580 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
32590 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
325a0 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
325b0 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
325c0 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
325d0 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
325e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
325f0 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
32600 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
32610 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
32620 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
32630 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
32640 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
32650 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32660 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
32670 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
32680 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
32690 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
326a0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
326b0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
326c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
326d0 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  *, double);.SQLI
326e0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
326f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32700 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32710 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
32720 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
32730 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
32740 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
32750 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
32760 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
32770 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
32780 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32790 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
327a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
327b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
327c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
327d0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
327e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
327f0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
32800 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32810 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
32820 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
32830 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
32840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32850 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
32860 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  ext*, int);.SQLI
32870 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32880 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
32890 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
328a0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
328b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
328c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
328d0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
328e0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
328f0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
32900 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
32910 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32920 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
32930 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
32940 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
32950 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32960 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
32970 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32980 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
32990 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
329a0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
329b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
329c0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
329d0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
329e0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
329f0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
32a00 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
32a10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
32a20 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
32a30 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
32a40 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
32a50 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
32a60 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
32a70 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
32a80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
32a90 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
32aa0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32ab0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
32ac0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
32ad0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
32ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32af0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
32b00 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
32b10 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
32b20 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
32b30 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
32b40 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
32b50 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
32b60 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
32b70 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
32b80 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
32b90 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
32ba0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
32bb0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
32bc0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
32bd0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
32be0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
32bf0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
32c00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
32c10 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
32c20 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
32c30 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
32c40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32c50 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
32c60 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
32c70 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
32c80 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
32c90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
32ca0 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
32cb0 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
32cc0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
32cd0 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
32ce0 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
32cf0 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
32d00 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
32d10 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
32d20 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
32d30 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
32d40 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
32d50 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
32d60 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
32d70 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
32d80 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
32d90 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
32da0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
32db0 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
32dc0 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
32dd0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
32de0 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
32df0 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
32e00 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
32e10 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
32e20 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
32e30 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
32e40 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
32e50 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
32e60 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
32e70 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
32e80 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
32e90 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
32ea0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
32eb0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
32ec0 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
32ed0 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
32ee0 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
32ef0 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
32f00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
32f10 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
32f20 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69  Arg, is an appli
32f30 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
32f40 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
32f50 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
32f60 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
32f70 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
32f80 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
32f90 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
32fa0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
32fb0 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
32fc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
32fd0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
32fe0 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
32ff0 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
33000 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
33010 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
33020 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
33030 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
33040 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
33050 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
33060 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
33070 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
33080 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
33090 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
330a0 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
330b0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
330c0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
330d0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
330e0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
330f0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
33100 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
33110 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33120 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
33130 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
33140 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
33150 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
33160 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
33170 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
33180 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
33190 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
331a0 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
331b0 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
331c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
331d0 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
331e0 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
331f0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
33200 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
33210 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
33220 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
33230 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
33240 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
33250 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
33260 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
33270 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
33280 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
33290 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
332a0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
332b0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
332c0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
332d0 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
332e0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
332f0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
33300 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
33310 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
33320 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
33330 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
33340 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
33350 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
33360 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
33370 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
33380 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
33390 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
333a0 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
333b0 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
333c0 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
333d0 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
333e0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
333f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33400 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
33410 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
33420 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
33430 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
33440 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
33450 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
33460 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
33470 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
33480 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
33490 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
334a0 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
334b0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
334c0 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
334d0 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
334e0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
334f0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
33500 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
33510 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
33520 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
33530 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33540 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
33550 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
33560 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
33570 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
33580 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
33590 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
335a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
335b0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
335c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
335d0 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
335e0 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
335f0 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
33600 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
33610 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
33620 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
33630 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
33640 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
33650 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
33660 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
33670 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
33680 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
33690 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
336a0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
336b0 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
336c0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
336d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
336e0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
336f0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
33700 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
33710 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
33720 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
33730 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
33740 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33750 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
33760 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
33770 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
33780 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
33790 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
337a0 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
337b0 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
337c0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
337d0 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
337e0 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
337f0 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
33800 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
33810 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
33820 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
33830 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
33840 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
33850 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
33860 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
33870 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
33880 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
33890 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
338a0 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
338b0 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
338c0 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
338d0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
338e0 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
338f0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
33900 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
33910 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33920 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
33930 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33940 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
33950 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33960 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33970 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
33980 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
33990 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
339a0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
339b0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
339c0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
339d0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
339e0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
339f0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
33a00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
33a10 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33a20 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
33a30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
33a40 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
33a50 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
33a60 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
33a70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
33a80 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
33a90 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
33aa0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
33ab0 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  oid*).);.SQLITE_
33ac0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
33ad0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33ae0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
33af0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
33b00 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
33b10 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
33b20 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
33b30 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
33b40 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
33b50 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
33b60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33b70 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
33b80 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  d Callbacks.**.*
33b90 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69  * ^To avoid havi
33ba0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
33bb0 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
33bc0 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
33bd0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
33be0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
33bf0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
33c00 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
33c10 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
33c20 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
33c30 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e  ection] to be in
33c40 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
33c50 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
33c60 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
33c70 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
33c80 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e  *.** ^If the fun
33c90 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
33ca0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
33cb0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33cc0 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
33cd0 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
33ce0 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
33cf0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
33d00 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
33d10 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
33d20 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49  ded in UTF-8. ^I
33d30 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
33d40 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
33d50 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e  s used,.** the n
33d60 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20  ames are passed 
33d70 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
33d80 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
33d90 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61   order..** ^A ca
33da0 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
33db0 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74  ction replaces t
33dc0 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c  he existing coll
33dd0 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c  ation-needed cal
33de0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57  lback..**.** ^(W
33df0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
33e00 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
33e10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
33e20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
33e30 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
33e40 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
33e50 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33e60 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
33e70 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
33e80 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
33e90 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
33ea0 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
33eb0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
33ec0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
33ed0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
33ee0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
33ef0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
33f00 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
33f10 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
33f20 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
33f30 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
33f40 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
33f50 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
33f60 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
33f70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
33f80 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
33f90 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
33fa0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
33fb0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ce.)^.**.** The 
33fc0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
33fd0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
33fe0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
33ff0 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
34000 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34010 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
34020 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34030 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
34040 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
34050 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
34060 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2()]..*/.SQLITE_
34070 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34080 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34090 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
340a0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
340b0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
340c0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
340d0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53  onst char*).);.S
340e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
340f0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
34100 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
34110 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
34120 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
34130 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
34140 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
34150 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
34160 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
34170 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
34180 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
34190 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
341a0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
341b0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
341c0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
341d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
341e0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
341f0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
34200 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
34210 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
34220 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
34230 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
34240 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34250 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
34260 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
34270 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
34280 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
34290 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
342a0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
342b0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
342c0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
342d0 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
342e0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
342f0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
34300 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
34310 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
34320 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
34330 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
34340 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
34350 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
34360 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
34370 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
34380 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
34390 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
343a0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
343b0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
343c0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
343d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
343e0 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
343f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
34400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34410 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
34420 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
34430 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
34440 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
34450 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
34460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
34470 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
34480 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
34490 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
344a0 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
344b0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
344c0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
344d0 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rk..*/.SQLITE_AP
344e0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  I void sqlite3_a
344f0 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63  ctivate_see(.  c
34500 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
34510 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
34520 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
34530 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
34540 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45  .#ifdef SQLITE_E
34550 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a  NABLE_CEROD./*.*
34560 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
34570 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
34580 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73   a CEROD databas
34590 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
345a0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
345b0 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74  f the CEROD rout
345c0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
345d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
345e0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
345f0 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
34600 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
34610 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
34620 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
34630 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
34640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
34650 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
34660 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
34670 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
34680 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
34690 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
346a0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
346b0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
346c0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
346d0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
346e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
346f0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
34700 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
34710 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
34720 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
34730 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
34740 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
34750 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
34760 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
34770 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
34780 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
34790 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
347a0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
347b0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
347c0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
347d0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
347e0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
347f0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
34800 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
34810 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
34820 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
34830 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
34840 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
34850 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
34860 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
34870 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
34880 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
34890 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
348a0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
348b0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
348c0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
348d0 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
348e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
348f0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
34900 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
34910 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
34920 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
34930 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
34940 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  aphs..*/.SQLITE_
34950 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34960 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
34970 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
34980 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
34990 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
349a0 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
349b0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
349c0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
349d0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
349e0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
349f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
34a00 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
34a10 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
34a20 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
34a30 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
34a40 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
34a50 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
34a60 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
34a70 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
34a80 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
34a90 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
34aa0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
34ab0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
34ac0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
34ad0 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
34ae0 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
34af0 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
34b00 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
34b10 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
34b20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
34b30 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
34b40 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
34b50 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
34b60 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
34b70 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
34b80 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
34b90 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
34ba0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
34bb0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
34bc0 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
34bd0 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
34be0 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
34bf0 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
34c00 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
34c10 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
34c20 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
34c30 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
34c40 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
34c50 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
34c60 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
34c70 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
34c80 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
34c90 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
34ca0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
34cb0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
34cc0 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
34cd0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
34ce0 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
34cf0 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
34d00 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
34d10 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
34d20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
34d30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
34d40 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
34d50 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
34d60 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
34d70 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
34d80 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
34d90 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
34da0 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
34db0 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
34dc0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
34dd0 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
34de0 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
34df0 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
34e00 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
34e10 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
34e20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
34e30 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
34e40 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
34e50 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
34e60 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
34e70 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
34e80 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
34e90 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
34ea0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
34eb0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
34ec0 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
34ed0 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
34ee0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
34ef0 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
34f00 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
34f10 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45  _API SQLITE_EXTE
34f20 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
34f30 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
34f40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34f50 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d  : Test For Auto-
34f60 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b  Commit Mode.** K
34f70 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f  EYWORDS: {autoco
34f80 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  mmit mode}.**.**
34f90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
34fa0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
34fb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34fc0 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
34fd0 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
34fe0 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
34ff0 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
35000 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
35010 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
35020 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f  tively.  ^Autoco
35030 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
35040 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e  by default..** ^
35050 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
35060 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
35070 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
35080 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  nt..** ^Autocomm
35090 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
350a0 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
350b0 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
350c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
350d0 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
350e0 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
350f0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
35100 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
35110 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
35120 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69   (errors includi
35130 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d  ng [SQLITE_FULL]
35140 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  , [SQLITE_IOERR]
35150 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ,.** [SQLITE_NOM
35160 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
35170 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
35180 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
35190 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   the.** transact
351a0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c  ion might be rol
351b0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
351c0 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c  ically.  The onl
351d0 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
351e0 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c   out whether SQL
351f0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
35200 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
35210 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
35220 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
35230 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
35240 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
35250 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
35260 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
35270 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
35280 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
35290 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  * connection whi
352a0 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
352b0 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
352c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
352d0 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
352e0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
352f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74   int sqlite3_get
35300 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
35310 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
35320 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65  PI3REF: Find The
35330 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
35340 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53   Of A Prepared S
35350 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
35360 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  The sqlite3_db_h
35370 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20  andle interface 
35380 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74  returns the [dat
35390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
353a0 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77  ] handle.** to w
353b0 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64  hich a [prepared
353c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
353d0 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61  ngs.  ^The [data
353e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
353f0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
35400 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
35410 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64  e is the same [d
35420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35430 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  on].** that was 
35440 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
35450 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
35460 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
35470 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
35480 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
35490 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
354a0 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
354b0 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
354c0 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54   place..*/.SQLIT
354d0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73  E_API sqlite3 *s
354e0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
354f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
35500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35510 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c  : Return The Fil
35520 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61  ename For A Data
35530 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
35540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35550 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44  e3_db_filename(D
35560 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
35570 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35580 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a  to a filename.**
35590 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
355a0 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63   database N of c
355b0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54  onnection D.  ^T
355c0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
355d0 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65   file.** has the
355e0 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49   name "main".  I
355f0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74  f there is no at
35600 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20  tached database 
35610 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  N on the databas
35620 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
35630 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61 73  D, or if databas
35640 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61  e N is a tempora
35650 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20  ry or in-memory 
35660 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a  database, then.*
35670 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
35680 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
35690 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  .** ^The filenam
356a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
356b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  is function is t
356c0 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65  he output of the
356d0 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  .** xFullPathnam
356e0 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  e method of the 
356f0 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65  [VFS].  ^In othe
35700 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c  r words, the fil
35710 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  ename.** will be
35720 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
35730 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74  hname, even if t
35740 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64  he filename used
35750 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  .** to open the 
35760 64 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61  database origina
35770 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f 72  lly was a URI or
35780 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61   relative pathna
35790 6d 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  me..*/.SQLITE_AP
357a0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
357b0 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d  lite3_db_filenam
357c0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  e(sqlite3 *db, c
357d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
357e0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
357f0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
35800 69 66 20 61 20 64 61 74 61 62 61 73 65 20 69 73  if a database is
35810 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a   read-only.**.**
35820 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
35830 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69  _readonly(D,N) i
35840 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35850 20 31 20 69 66 20 74 68 65 20 64 61 74 61 62 61   1 if the databa
35860 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65  se N.** of conne
35870 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61 64 2d  ction D is read-
35880 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20 69 73  only, 0 if it is
35890 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f 72 20   read/write, or 
358a0 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a  -1 if N is not.*
358b0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
358c0 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e  database on conn
358d0 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53 51 4c  ection D..*/.SQL
358e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
358f0 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28  te3_db_readonly(
35900 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e  sqlite3 *db, con
35910 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
35920 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35930 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
35940 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
35950 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
35960 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35970 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
35980 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
35990 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
359a0 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
359b0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
359c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
359d0 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
359e0 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
359f0 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
35a00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
35a10 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
35a20 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
35a30 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
35a40 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
35a50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35a60 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
35a70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35a80 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
35a90 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
35aa0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
35ab0 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
35ac0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
35ad0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35ae0 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
35af0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
35b00 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
35b10 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
35b20 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
35b30 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
35b40 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
35b50 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
35b60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
35b70 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
35b80 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
35b90 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
35ba0 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
35bb0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
35bc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35bd0 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
35be0 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
35bf0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
35c00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35c10 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
35c20 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
35c30 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
35c40 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
35c50 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
35c60 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
35c70 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69   [COMMIT | commi
35c80 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  tted]..** ^Any c
35c90 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
35ca0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
35cb0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
35cc0 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
35cd0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
35ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
35cf0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
35d00 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
35d10 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
35d20 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
35d30 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
35d40 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
35d50 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
35d60 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52  ransaction is [R
35d70 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64  OLLBACK | rolled
35d80 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20   back]..** ^Any 
35d90 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
35da0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
35db0 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  to sqlite3_rollb
35dc0 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  ack_hook().** fo
35dd0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
35de0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
35df0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
35e00 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d   ^The pArg argum
35e10 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
35e20 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
35e30 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68  lback..** ^If th
35e40 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
35e50 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
35e60 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
35e70 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
35e80 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
35e90 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
35ea0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
35eb0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
35ec0 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e  t_hook(D,C,P) an
35ed0 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  d sqlite3_rollba
35ee0 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  ck_hook(D,C,P) f
35ef0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
35f00 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  rn the P argumen
35f10 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
35f20 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20  ous call of the 
35f30 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
35f40 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
35f50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35f60 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
35f70 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
35f80 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e  all for each fun
35f90 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a  ction on D..**.*
35fa0 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64  * The commit and
35fb0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63   rollback hook c
35fc0 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74  allbacks are not
35fd0 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54   reentrant..** T
35fe0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c  he callback impl
35ff0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
36000 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
36010 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
36020 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
36030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
36040 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c   invoked the cal
36050 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69  lback.  Any acti
36060 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
36070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
36080 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
36090 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
360a0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
360b0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
360c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
360d0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
360e0 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a  red the commit.*
360f0 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  * or rollback ho
36100 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ok in the first 
36110 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  place..** Note t
36120 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  hat running any 
36130 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d  other SQL statem
36140 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ents, including 
36150 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
36160 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20  s,.** or merely 
36170 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
36180 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
36190 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
361a0 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  ()] will modify.
361b0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
361c0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
361d0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
361e0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
361f0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
36200 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20   ^Registering a 
36210 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
36220 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
36230 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ack..**.** ^When
36240 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
36250 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
36260 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  e returns zero, 
36270 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  the [COMMIT].** 
36280 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c  operation is all
36290 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65  owed to continue
362a0 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20   normally.  ^If 
362b0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a  the commit hook.
362c0 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
362d0 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43  ero, then the [C
362e0 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72  OMMIT] is conver
362f0 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c  ted into a [ROLL
36300 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  BACK]..** ^The r
36310 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
36320 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
36330 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
36340 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
36350 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
36360 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
36370 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
36380 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
36390 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
363a0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
363b0 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
363c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
363d0 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
363e0 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
363f0 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
36400 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
36410 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
36420 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
36430 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
36440 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
36450 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
36460 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  cur..** ^The rol
36470 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
36480 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
36490 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
364a0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
364b0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
364c0 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
364d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
364e0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
364f0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
36500 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
36510 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  k()] interface..
36520 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
36530 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  id *sqlite3_comm
36540 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  it_hook(sqlite3*
36550 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
36560 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
36570 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
36580 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
36590 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
365a0 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
365b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
365c0 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
365d0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
365e0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
365f0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
36600 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
36610 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
36620 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
36630 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
36640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36650 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
36660 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
36670 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
36680 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
36690 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
366a0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
366b0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
366c0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
366d0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
366e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
366f0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
36700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36710 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
36720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
36730 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
36740 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
36750 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
36760 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
36770 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
36780 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
36790 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
367a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
367b0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
367c0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
367d0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
367e0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
367f0 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
36800 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
36810 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
36820 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
36830 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
36840 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
36850 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
36860 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
36870 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
36880 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
36890 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
368a0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
368b0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
368c0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
368d0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
368e0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
368f0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
36900 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
36910 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
36920 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
36930 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
36940 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
36950 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
36960 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
36970 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
36980 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
36990 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
369a0 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
369b0 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
369c0 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
369d0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
369e0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
369f0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
36a00 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
36a10 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
36a20 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
36a30 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
36a40 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
36a50 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
36a60 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
36a70 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
36a80 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
36a90 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
36aa0 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
36ab0 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
36ac0 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
36ad0 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
36ae0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
36af0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
36b00 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
36b10 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
36b20 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
36b30 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
36b40 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
36b50 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
36b60 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
36b70 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
36b80 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
36b90 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
36ba0 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
36bb0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
36bc0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
36bd0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
36be0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36bf0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
36c00 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
36c10 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
36c20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
36c30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36c40 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
36c50 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
36c60 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
36c70 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
36c80 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
36c90 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
36ca0 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
36cb0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
36cc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
36cd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
36ce0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
36cf0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
36d00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
36d10 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
36d20 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
36d30 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
36d40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36d50 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
36d60 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  ,C,P) function.*
36d70 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  * returns the P 
36d80 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
36d90 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a  e previous call.
36da0 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
36db0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36dc0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
36dd0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
36de0 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a   call on D..**.*
36df0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
36e00 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
36e10 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
36e20 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
36e30 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
36e40 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
36e50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
36e60 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
36e70 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
36e80 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
36e90 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
36ea0 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
36eb0 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
36ec0 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
36ed0 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
36ee0 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50  Disable Shared P
36ef0 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45  ager Cache.** KE
36f00 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
36f10 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54  cache}.**.** ^(T
36f20 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
36f30 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
36f40 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
36f50 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
36f60 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
36f70 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
36f80 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73  between [databas
36f90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63  e connection | c
36fa0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74  onnections].** t
36fb0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
36fc0 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20  ase. Sharing is 
36fd0 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
36fe0 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a  rgument is true.
36ff0 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ** and disabled 
37000 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
37010 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a  is false.)^.**.*
37020 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67  * ^Cache sharing
37030 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
37040 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
37050 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
37060 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
37070 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
37080 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
37090 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
370a0 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
370b0 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
370c0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
370d0 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
370e0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
370f0 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68  * ^(The cache sh
37100 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
37110 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
37120 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
37130 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
37140 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
37150 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
37160 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
37170 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
37180 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
37190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
371a0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
371b0 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
371c0 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
371d0 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
371e0 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
371f0 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  ened.)^.**.** ^(
37200 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
37210 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
37220 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
37230 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
37240 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
37250 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
37260 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
37270 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
37280 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65  .)^.**.** ^Share
37290 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
372a0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
372b0 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
372c0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
372d0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
372e0 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
372f0 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
37300 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
37310 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
37320 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
37330 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  citly..**.** See
37340 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20   Also:  [SQLite 
37350 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64  Shared-Cache Mod
37360 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e].*/.SQLITE_API
37370 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61   int sqlite3_ena
37380 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
37390 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
373a0 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20  PI3REF: Attempt 
373b0 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
373c0 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ory.**.** ^The s
373d0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
373e0 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63  emory() interfac
373f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72  e attempts to fr
37400 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ee N bytes.** of
37410 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
37420 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
37430 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
37440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a  y allocations.**
37450 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
37460 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20  abase library.  
37470 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20   Memory used to 
37480 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a  cache database.*
37490 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  * pages to impro
374a0 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69  ve performance i
374b0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
374c0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
374d0 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  mory..** ^sqlite
374e0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
374f0 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  () returns the n
37500 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61  umber of bytes a
37510 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a  ctually freed,.*
37520 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  * which might be
37530 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68   more or less th
37540 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65  an the amount re
37550 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  quested..** ^The
37560 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
37570 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e  _memory() routin
37580 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74  e is a no-op ret
37590 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69  urning zero.** i
375a0 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20  f SQLite is not 
375b0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
375c0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
375d0 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
375e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
375f0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c   [sqlite3_db_rel
37600 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a  ease_memory()].*
37610 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
37620 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
37630 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
37640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
37650 72 65 65 20 4d 65 6d 6f 72 79 20 55 73 65 64 20  ree Memory Used 
37660 42 79 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  By A Database Co
37670 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
37680 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  The sqlite3_db_r
37690 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 44 29  elease_memory(D)
376a0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
376b0 70 74 73 20 74 6f 20 66 72 65 65 20 61 73 20 6d  pts to free as m
376c0 75 63 68 20 68 65 61 70 0a 2a 2a 20 6d 65 6d 6f  uch heap.** memo
376d0 72 79 20 61 73 20 70 6f 73 73 69 62 6c 65 20 66  ry as possible f
376e0 72 6f 6d 20 64 61 74 61 62 61 73 65 20 63 6f 6e  rom database con
376f0 6e 65 63 74 69 6f 6e 20 44 2e 20 55 6e 6c 69 6b  nection D. Unlik
37700 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
37710 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
37720 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
37730 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
37740 20 65 66 66 65 63 74 20 65 76 65 6e 0a 2a 2a 20   effect even.** 
37750 77 68 65 6e 20 74 68 65 6e 20 5b 53 51 4c 49 54  when then [SQLIT
37760 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
37770 4d 41 4e 41 47 45 4d 45 4e 54 5d 20 63 6f 6d 70  MANAGEMENT] comp
37780 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
37790 69 73 0a 2a 2a 20 6f 6d 69 74 74 65 64 2e 0a 2a  is.** omitted..*
377a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
377b0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
377c0 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 53 51 4c  memory()].*/.SQL
377d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
377e0 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d  te3_db_release_m
377f0 65 6d 6f 72 79 28 73 71 6c 69 74 65 33 2a 29 3b  emory(sqlite3*);
37800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37810 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74  : Impose A Limit
37820 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a   On Heap Size.**
37830 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37840 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
37850 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
37860 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69  ets and/or queri
37870 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c  es the.** soft l
37880 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
37890 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
378a0 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
378b0 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
378c0 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74  e..** ^SQLite st
378d0 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65  rives to keep he
378e0 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a  ap memory utiliz
378f0 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20  ation below the 
37900 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d  soft heap.** lim
37910 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20 74  it by reducing t
37920 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
37930 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70  es held in the p
37940 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20  age cache.** as 
37950 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67  heap memory usag
37960 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74 68  es approaches th
37970 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
37980 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37990 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61 75   is "soft" becau
379a0 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53  se even though S
379b0 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
379c0 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74   stay.** below t
379d0 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c  he limit, it wil
379e0 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d  l exceed the lim
379f0 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20 67  it rather than g
37a00 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53  enerate.** an [S
37a10 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72  QLITE_NOMEM] err
37a20 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  or.  In other wo
37a30 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65  rds, the soft he
37a40 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20  ap limit .** is 
37a50 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
37a60 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
37a70 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
37a80 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
37a90 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20 73  mit64() is the s
37aa0 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f  ize of.** the so
37ab0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72  ft heap limit pr
37ac0 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2c  ior to the call,
37ad0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 69 6e 20   or negative in 
37ae0 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 0a 2a  the case of an.*
37af0 2a 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  * error.  ^If th
37b00 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20  e argument N is 
37b10 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e  negative.** then
37b20 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61   no change is ma
37b30 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68  de to the soft h
37b40 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63  eap limit.  Henc
37b50 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  e, the current.*
37b60 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f  * size of the so
37b70 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
37b80 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
37b90 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  by invoking.** s
37ba0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
37bb0 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68 20  _limit64() with 
37bc0 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d  a negative argum
37bd0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ent..**.** ^If t
37be0 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
37bf0 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73   zero then the s
37c00 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
37c10 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
37c20 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61  * ^(The soft hea
37c30 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65  p limit is not e
37c40 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63  nforced in the c
37c50 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
37c60 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20  ation.** if one 
37c70 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f  or more of follo
37c80 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20  wing conditions 
37c90 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20  are true:.**.** 
37ca0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
37cb0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37cc0 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e   is set to zero.
37cd0 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20  .** <li> Memory 
37ce0 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69  accounting is di
37cf0 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63  sabled using a c
37d00 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68  ombination of th
37d10 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  e.**      [sqlit
37d20 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
37d30 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
37d40 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d  TUS],...) start-
37d50 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a  time option and.
37d60 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c  **      the [SQL
37d70 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
37d80 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74  TATUS] compile-t
37d90 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
37da0 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69  li> An alternati
37db0 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ve page cache im
37dc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
37dd0 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a  specified using.
37de0 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
37df0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
37e00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
37e10 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  ,...)..** <li> T
37e20 68 65 20 70 61 67 65 20 63 61 63 68 65 20 61 6c  he page cache al
37e30 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73  locates from its
37e40 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c   own memory pool
37e50 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20   supplied.**    
37e60 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f    by [sqlite3_co
37e70 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
37e80 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c  NFIG_PAGECACHE],
37e90 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e  ...) rather than
37ea0 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68  .**      from th
37eb0 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e  e heap..** </ul>
37ec0 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69  )^.**.** Beginni
37ed0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
37ee0 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68  ersion 3.7.3, th
37ef0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37f00 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a  t is enforced.**
37f10 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
37f20 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
37f30 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
37f40 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
37f50 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  NT].** compile-t
37f60 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ime option is in
37f70 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51  voked.  With [SQ
37f80 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
37f90 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a  RY_MANAGEMENT],.
37fa0 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ** the soft heap
37fb0 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63   limit is enforc
37fc0 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f  ed on every memo
37fd0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20  ry allocation.  
37fe0 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49  Without.** [SQLI
37ff0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
38000 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68  _MANAGEMENT], th
38010 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
38020 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63  t is only enforc
38030 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72  ed.** when memor
38040 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62  y is allocated b
38050 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  y the page cache
38060 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67 67 65  .  Testing sugge
38070 73 74 73 20 74 68 61 74 20 62 65 63 61 75 73 65  sts that because
38080 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61 63  .** the page cac
38090 68 65 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d  he is the predom
380a0 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65  inate memory use
380b0 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73  r in SQLite, mos
380c0 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
380d0 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61  s will achieve a
380e0 64 65 71 75 61 74 65 20 73 6f 66 74 20 68 65 61  dequate soft hea
380f0 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d  p limit enforcem
38100 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74  ent without.** t
38110 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54  he use of [SQLIT
38120 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
38130 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a  MANAGEMENT]..**.
38140 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74 61  ** The circumsta
38150 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69 63 68  nces under which
38160 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66   SQLite will enf
38170 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20 68 65  orce the soft he
38180 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20  ap limit may.** 
38190 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72  changes in futur
381a0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
381b0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
381c0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
381d0 34 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  4 sqlite3_soft_h
381e0 65 61 70 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69  eap_limit64(sqli
381f0 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f  te3_int64 N);../
38200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
38210 65 70 72 65 63 61 74 65 64 20 53 6f 66 74 20 48  eprecated Soft H
38220 65 61 70 20 4c 69 6d 69 74 20 49 6e 74 65 72 66  eap Limit Interf
38230 61 63 65 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ace.** DEPRECATE
38240 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  D.**.** This is 
38250 61 20 64 65 70 72 65 63 61 74 65 64 20 76 65 72  a deprecated ver
38260 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  sion of the [sql
38270 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
38280 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74  imit64()].** int
38290 65 72 66 61 63 65 2e 20 20 54 68 69 73 20 72 6f  erface.  This ro
382a0 75 74 69 6e 65 20 69 73 20 70 72 6f 76 69 64 65  utine is provide
382b0 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
382c0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
382d0 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77  * only.  All new
382e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
382f0 6f 75 6c 64 20 75 73 65 20 74 68 65 0a 2a 2a 20  ould use the.** 
38300 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
38310 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e  ap_limit64()] in
38320 74 65 72 66 61 63 65 20 72 61 74 68 65 72 20 74  terface rather t
38330 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f  han this one..*/
38340 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
38350 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
38360 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
38370 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e  heap_limit(int N
38380 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
38390 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74  REF: Extract Met
383a0 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f  adata About A Co
383b0 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a  lumn Of A Table.
383c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
383d0 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61  ine returns meta
383e0 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65  data about a spe
383f0 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20  cific column of 
38400 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61  a specific.** da
38410 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63  tabase table acc
38420 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68  essible using th
38430 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38440 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
38450 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
38460 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61  first function a
38470 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
38480 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64  The column is id
38490 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
384a0 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e  second, third an
384b0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
384c0 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66  ers to.** this f
384d0 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65  unction. ^The se
384e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
384f0 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d  s either the nam
38500 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
38510 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e  e.** (i.e. "main
38520 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e  ", "temp", or an
38530 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
38540 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  se) containing t
38550 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  he specified.** 
38560 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e  table or NULL. ^
38570 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
38580 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
38590 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
385a0 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
385b0 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
385c0 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
385d0 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61  m used by the da
385e0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f  tabase engine to
385f0 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75  .** resolve unqu
38600 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65  alified table re
38610 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  ferences..**.** 
38620 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
38630 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
38640 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
38650 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20  n are the table 
38660 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61  and column.** na
38670 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65  me of the desire
38680 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63  d column, respec
38690 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20  tively. Neither 
386a0 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74  of these paramet
386b0 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  ers.** may be NU
386c0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64  LL..**.** ^Metad
386d0 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20  ata is returned 
386e0 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68  by writing to th
386f0 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f  e memory locatio
38700 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ns passed as the
38710 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73   5th.** and subs
38720 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72  equent parameter
38730 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
38740 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73  on. ^Any of thes
38750 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20  e arguments may 
38760 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77  be.** NULL, in w
38770 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f  hich case the co
38780 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d  rresponding elem
38790 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20  ent of metadata 
387a0 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a  is omitted..**.*
387b0 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  * ^(<blockquote>
387c0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
387d0 72 3d 22 31 2