System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 769736fc5dacbecfd2a8f68942dba355cb541cad:


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 36 22 0a 23 64 65 66 69 6e 65 20 53  .7.16".#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 36 0a 23 64 65  MBER 3007016.#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 33  CE_ID      "2013
1070: 2d 30 32 2d 31 35 20 30 34 3a 32 31 3a 30 31 20  -02-15 04:21:01 
1080: 38 34 33 65 31 63 35 34 33 61 61 62 61 62 38 63  843e1c543aabab8c
1090: 64 36 32 66 32 38 37 34 32 64 35 38 31 38 38 38  d62f28742d581888
10a0: 37 64 33 36 62 63 62 37 22 0a 0a 2f 2a 0a 2a 2a  7d36bcb7"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
24a0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
24b0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
24c0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
24d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
24e0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
24f0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2500: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2510: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2530: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2540: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
2550: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
2560: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
2570: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
2580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2590: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
25a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25b0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
25c0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
25d0: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
25e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
25f0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2600: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2610: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2620: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2630: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2640: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
2650: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
2660: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
2670: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
2680: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2690: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26a0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
26b0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
26c0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
26d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
26e0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
26f0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2700: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2710: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2720: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2730: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2740: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
2750: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
2760: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2770: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
2780: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
2790: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
27b0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
27c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
27d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
27e0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
27f0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2800: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2810: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2820: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2830: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2850: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
2870: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2880: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2890: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
28a0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
28b0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
28c0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
28d0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
28e0: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
28f0: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2900: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2910: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2930: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2940: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2950: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2960: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
2970: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2980: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
29a0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
29b0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
29c0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
29d0: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
29e0: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
29f0: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2a00: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2a10: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2a20: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2a30: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2a40: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2a50: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2a60: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
2a70: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
2a80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2aa0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2ab0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2ac0: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
2ad0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2ae0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2af0: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2b00: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2b10: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2b20: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2b30: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b40: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2b60: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
2b70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
2b80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
2b90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
2ba0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
2bb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
2bc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2bd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
2c00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
2c10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
2c20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
2c30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2c40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
2c50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
2c60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
2c70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
2c80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
2c90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
2ca0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
2cb0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2cd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2ce0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
2cf0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66  ments.** and unf
2d00: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2d10: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68  backups, then th
2d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d30: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a  ction becomes.**
2d40: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f   an unusable "zo
2d50: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c  mbie" which will
2d60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
2d70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68  e deallocated wh
2d80: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70  en the.** last p
2d90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f  t is finalized o
2db0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  r the last sqlit
2dc0: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20  e3_backup is.** 
2dd0: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73  finished.  The s
2de0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2df0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
2e00: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2e10: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e  with.** host lan
2e20: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20  guages that are 
2e30: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65  garbage collecte
2e40: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65  d, and where the
2e50: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a   order in which.
2e60: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61  ** destructors a
2e70: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62  re called is arb
2e80: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70  itrary..**.** Ap
2e90: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2eb0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
2ec0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
2ed0: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73  atements],.** [s
2ee0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2ef0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2f00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
2f10: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f20: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20  backup_finish | 
2f30: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c  finish] all [sql
2f40: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
2f50: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a  ects associated.
2f60: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
2f70: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2f80: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2f90: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2fa0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71  ject.  ^If.** sq
2fb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 73  lite3_close() is
2fc0: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2fd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fe0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2ff0: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3030: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
3050: 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  it returns SQLIT
3060: 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61  E_OK but the dea
3070: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
3080: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
3090: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
30a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30b0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
30c0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
30d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
30e0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
30f0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
3100: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
3110: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
3120: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
3130: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
3140: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
3150: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
3160: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
3170: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
3180: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3190: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
31a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
31b0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
31c0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
31d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
31e0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
31f0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
3200: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3210: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
3220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
3230: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
3240: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
3250: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
3260: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
3270: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
3280: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
3290: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
32a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
32b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
32c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
32d0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
32e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
32f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
3300: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3310: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3320: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3330: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3340: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3350: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3360: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3370: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3380: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
3390: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
33a0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
33b0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
33c0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
33d0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
33e0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
33f0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
3400: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3410: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3420: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
3430: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3440: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3450: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3460: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3470: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3480: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3490: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
34a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
34c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
34d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
34e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
34f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3500: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3510: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3520: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3530: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3540: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3550: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3560: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3570: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3580: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3590: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
35a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
35b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
35c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
35e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
35f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3600: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3610: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3620: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3630: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3640: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3650: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3660: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3670: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3680: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3690: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
36a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
36b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
36c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
36d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
36e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
36f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3700: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3710: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3720: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3730: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3740: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3750: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3760: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3770: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3780: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3790: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
37a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
37b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
37c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
37d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
37e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
37f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3800: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3810: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3820: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3830: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3840: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3850: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3860: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3870: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3880: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3890: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
38a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
38b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
38d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
38e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3900: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3910: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3920: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3930: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3940: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3950: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3960: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3970: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3980: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3990: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
39a0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
39b0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
39c0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
39d0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39e0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39f0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3a00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3a10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3a20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3a30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3a40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3a50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3a60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3a70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3a80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3a90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3aa0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3ab0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3ac0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3ad0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3ae0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3af0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3b00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3b10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3b20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3b30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3b40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3b60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3b70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3b80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3b90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3ba0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3bb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3bc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3bd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3be0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3bf0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3c00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3c10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3c20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3c30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3c40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3c50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3c60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3c70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3c80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3ca0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3cb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3cc0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3cd0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3ce0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3cf0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3d00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3d10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3d20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3d30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3d40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3d50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3d60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3d70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3d80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3d90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3da0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3db0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3dc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3dd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3de0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3df0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3e00: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3e10: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3e20: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3e30: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
3e40: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
3e50: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3e60: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3e70: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3e80: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3e90: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3ea0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3eb0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3ec0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3ed0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ee0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3ef0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3f00: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3f10: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3f20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f30: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3f40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3f50: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3f60: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3f70: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3f80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3f90: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3fa0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3fb0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3fc0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3fd0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3fe0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3ff0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4000: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4010: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4020: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4030: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
4040: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
4050: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
4060: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
4070: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40a0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
40b0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
40c0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
40f0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4100: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4110: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4120: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4130: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4140: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4170: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
4180: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
4190: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
41c0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
41d0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
41e0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
41f0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4200: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4220: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4230: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4240: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4250: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
4260: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4270: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4280: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4290: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
42a0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
42b0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
42c0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
42d0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
42e0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
42f0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4300: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4310: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4320: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4330: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4340: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4350: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
4360: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
4370: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
4380: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
43a0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
43b0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
43c0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
43d0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
43e0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43f0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4400: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4410: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4420: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4440: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4450: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4460: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4490: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
44a0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
44b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44c0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
44d0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
44e0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44f0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4510: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4520: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4530: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4550: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4560: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4570: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4580: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4590: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
45a0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
45b0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
45c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
45d0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
45e0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45f0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4600: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4620: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4630: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4640: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4650: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4670: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4680: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4690: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
46a0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
46b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
46c0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
46d0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
46e0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4700: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4710: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4720: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4730: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4760: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4770: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4780: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47a0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47b0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
47c0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
47d0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
47e0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47f0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4800: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4810: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4830: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4840: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4860: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4870: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4880: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4890: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
48a0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
48b0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
48c0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
48d0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48f0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4900: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4910: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4920: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4930: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4940: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4950: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4970: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4980: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4990: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
49b0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
49c0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
49d0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
49e0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4a00: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4a10: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4a20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4a30: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4a40: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a50: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a60: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a70: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a80: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a90: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4aa0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4ab0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ad0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4ae0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4af0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4b00: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4b10: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4b20: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b30: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b40: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b50: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b60: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b70: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b80: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b90: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ba0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4bb0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4bc0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4bd0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4be0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bf0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4c00: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4c10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4c20: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c50: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c60: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c70: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c80: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c90: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4ca0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4cb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4cc0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4cd0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4ce0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cf0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4d00: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4d10: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4d20: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d30: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d50: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d60: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d70: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d80: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d90: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4da0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4db0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4dc0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4dd0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4de0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4df0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4e00: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4e10: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4e20: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e30: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e50: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e60: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e80: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e90: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4ea0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4eb0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4ec0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ed0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4ee0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ef0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4f00: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4f10: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4f20: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f30: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4f40: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4f50: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4f60: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4f70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4f80: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4f90: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4fa0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4fb0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4fc0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4fd0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4fe0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4ff0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
5000: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
5010: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
5020: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5080: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
51e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51f0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5200: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5210: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5230: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5240: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5250: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52d0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5380: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5390: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5540: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5550: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
55f0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5600: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5610: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5630: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5640: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5650: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5670: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5690: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
56a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
56b0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
56c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
56d0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
56e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56f0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5700: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5710: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5720: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5730: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5740: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5750: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
5760: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5770: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5780: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57b0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
57c0: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
57d0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
57e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57f0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5800: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5810: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5820: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5830: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5840: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5850: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5860: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5880: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5890: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
58a0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
58b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58c0: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
58d0: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
58e0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
58f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5900: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5910: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5920: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5930: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5940: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5950: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5960: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5970: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5990: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
59b0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
59c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
59d0: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
59e0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
59f0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5a00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5a20: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5a30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5a40: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5a50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a60: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a80: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 0a 2f 2a 0a  T | (9<<8))../*.
5a90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5aa0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5ab0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5ac0: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5ad0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5ae0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5af0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5b00: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5b10: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5b20: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5b30: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5b40: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5b50: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5b60: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5b70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5b80: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5b90: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5ba0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5bb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5bc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5bd0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5be0: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5bf0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5c00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5c10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5c20: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5c30: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5c40: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5c50: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5c60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5c70: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5c80: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5c90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5ca0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5cb0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5cc0: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5cd0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5ce0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5cf0: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5d00: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5d10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5d20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5d30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5d40: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5d50: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5d60: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5d70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
5d80: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
5d90: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
5da0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5db0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5dc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5dd0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5de0: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
5df0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5e10: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5e20: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
5e30: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
5e50: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
5e60: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
5e70: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5e90: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
5ea0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
5eb0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5ec0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5ed0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
5ee0: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
5ef0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
5f10: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
5f20: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
5f30: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
5f50: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
5f60: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
5f70: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
5f90: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
5fa0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
5fb0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fc0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
5fe0: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
5ff0: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6000: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6010: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6020: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
6030: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
6040: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
6050: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6060: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6070: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6080: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6090: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
60a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
60b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
60d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
60e0: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6100: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6110: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6120: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6130: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6140: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
6150: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
6160: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6170: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6180: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6190: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
61a0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
61b0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
61c0: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
61d0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
61e0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
61f0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6200: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6210: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6220: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6230: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6240: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6250: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
6260: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6270: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6280: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6290: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
62a0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
62b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
62c0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
62d0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
62e0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
62f0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6300: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6310: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6320: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6330: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6340: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6350: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
6360: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6370: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6380: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6390: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
63a0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
63b0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
63c0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
63d0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
63e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
63f0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6400: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6410: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6420: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6430: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6440: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6450: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
6460: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6470: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6480: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6490: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
64a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
64b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
64c0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
64d0: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
64e0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
64f0: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6500: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6510: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6520: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6530: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6540: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6550: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
6560: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6570: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6580: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6590: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
65a0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
65b0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a  e unchanged..*/.
65c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
65d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
65e0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
65f0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6600: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6610: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6620: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6640: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6650: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6660: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
6670: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6680: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6690: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
66a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
66b0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
66c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
66d0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
66e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
66f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6700: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
6710: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6720: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
6730: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6750: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
6760: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6770: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
6780: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6790: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
67a0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
67b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
67c0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
67d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
67e0: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
67f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6800: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
6810: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
6820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6830: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
6840: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
6850: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
6860: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6870: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
6880: 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a  0x00001000../*.*
6890: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
68a0: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
68b0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
68c0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
68d0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
68e0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
68f0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6900: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
6910: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6920: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
6930: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
6940: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6950: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
6960: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6970: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
6980: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6990: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
69a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
69b0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
69c0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
69d0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
69e0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
69f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6a00: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
6a10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
6a20: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
6a30: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
6a40: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
6a50: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
6a60: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
6a70: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6a80: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
6a90: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
6aa0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
6ab0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6ac0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
6ad0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
6ae0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6af0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
6b00: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
6b10: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
6b20: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
6b30: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
6b40: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
6b50: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
6b60: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
6b70: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
6b80: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6b90: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
6ba0: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
6bb0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
6bc0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
6bd0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
6be0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
6bf0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6c00: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
6c10: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6c20: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6c30: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6c40: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6c50: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
6c60: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
6c70: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
6c80: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6c90: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
6ca0: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
6cb0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6cc0: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
6cd0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6ce0: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
6cf0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
6d00: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
6d10: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
6d20: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
6d30: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
6d40: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
6d50: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
6d60: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
6d70: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
6d80: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6d90: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6da0: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
6db0: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
6dc0: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
6dd0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
6de0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
6df0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
6e00: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
6e10: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
6e20: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
6e30: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
6e40: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
6e50: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
6e60: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
6e70: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
6e80: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
6e90: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6ea0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6eb0: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
6ec0: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
6ed0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
6ee0: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
6ef0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
6f00: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
6f10: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
6f20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6f30: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
6f40: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
6f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6f60: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
6f70: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
6f80: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6f90: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
6fa0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6fb0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
6fc0: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
6fd0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
6fe0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
6ff0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
7000: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
7010: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
7020: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
7030: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
7040: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
7050: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
7060: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
7070: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
7080: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
7090: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
70a0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
70b0: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
70c0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
70d0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
70e0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
70f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7100: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
7110: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
7120: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
7130: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
7140: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
7150: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7160: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
7170: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
7180: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
7190: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
71a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
71b0: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
71c0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
71d0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
71e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
71f0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
7200: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
7210: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
7220: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
7230: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
7240: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7250: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
7260: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7270: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
7280: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
7290: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
72a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
72b0: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
72c0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
72d0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
72e0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
72f0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
7300: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
7310: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
7320: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
7330: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
7340: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
7350: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7360: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
7370: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
7380: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7390: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
73a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
73b0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
73c0: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
73d0: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
73e0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
73f0: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
7400: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
7410: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
7420: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7430: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
7440: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
7450: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
7460: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
7470: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
7480: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
7490: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
74a0: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
74b0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
74c0: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
74d0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
74e0: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
74f0: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
7500: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7510: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
7520: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
7530: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
7540: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
7550: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
7560: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
7570: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
7580: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
7590: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
75a0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
75b0: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
75c0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
75d0: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
75e0: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
75f0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
7600: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
7610: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
7620: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
7630: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
7640: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
7650: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
7660: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
7670: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
7680: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7690: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
76a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
76b0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
76c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
76d0: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
76e0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
76f0: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
7700: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7710: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
7720: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
7730: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
7740: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
7750: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7760: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
7770: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
7780: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
7790: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
77a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
77b0: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
77c0: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
77d0: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
77e0: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
77f0: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7800: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
7810: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
7820: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
7830: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
7840: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
7850: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
7860: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
7870: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
7880: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
7890: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
78a0: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
78b0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
78c0: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
78d0: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
78e0: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
78f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7900: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
7910: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
7920: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
7930: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
7940: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
7950: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
7960: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
7970: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
7980: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
7990: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
79a0: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
79b0: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
79c0: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
79d0: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
79e0: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
79f0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7a00: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
7a10: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
7a20: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
7a30: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
7a40: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
7a50: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
7a60: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
7a70: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
7a80: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
7a90: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
7aa0: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
7ab0: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
7ac0: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
7ad0: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
7ae0: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
7af0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
7b00: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
7b10: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ** A [SQLITE_FCN
7b20: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c  TL_LOCKSTATE | l
7b30: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
7b40: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
7b50: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
7b60: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
7b70: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
7b80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7b90: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
7ba0: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
7bb0: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
7bc0: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
7bd0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7be0: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
7bf0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
7c00: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
7c10: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7c20: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
7c30: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
7c40: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
7c50: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
7c60: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
7c70: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
7c80: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
7c90: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
7ca0: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
7cb0: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
7cc0: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
7cd0: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
7ce0: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
7cf0: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
7d00: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
7d10: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
7d20: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
7d30: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7d40: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
7d50: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
7d60: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
7d70: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
7d80: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7d90: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7da0: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
7db0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7dc0: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
7dd0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7de0: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
7df0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7e00: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
7e10: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7e20: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
7e30: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7e40: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
7e50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7e60: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
7e70: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7e80: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
7e90: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7ea0: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
7eb0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7ec0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
7ed0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7ee0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
7ef0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
7f00: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7f10: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
7f20: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
7f30: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
7f40: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
7f50: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7f60: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
7f70: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
7f80: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
7f90: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
7fa0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
7fb0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
7fc0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
7fd0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
7fe0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
7ff0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
8000: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8010: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
8020: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
8030: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
8040: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
8050: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
8060: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
8070: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
8080: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
8090: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
80a0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
80b0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
80c0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
80d0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
80e0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
80f0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8100: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
8110: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
8120: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
8130: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8140: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
8150: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
8160: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
8170: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
8180: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
8190: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
81a0: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
81b0: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
81c0: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
81d0: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
81e0: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
81f0: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8200: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
8210: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
8220: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
8230: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8240: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
8250: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8260: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8270: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
8280: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
8290: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
82a0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
82b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
82c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
82d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
82e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
82f0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8300: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8310: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8320: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
8330: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8340: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8350: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8360: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
8370: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
8380: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8390: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
83a0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
83b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
83c0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
83d0: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
83e0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
83f0: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8400: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8410: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8420: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8430: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8440: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8450: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
8460: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8470: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
8480: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
8490: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
84a0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
84b0: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
84c0: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
84d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
84e0: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
84f0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8510: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8520: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8530: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
8540: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
8550: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8560: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
8570: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
8580: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
8590: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
85a0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
85b0: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
85c0: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
85d0: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
85e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
85f0: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8600: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8610: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8620: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8630: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8640: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
8650: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
8660: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
8670: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
8680: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
8690: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
86a0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
86b0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a  rol Opcodes.**.*
86c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
86d0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
86e0: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
86f0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8700: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
8710: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8720: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
8730: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8740: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
8750: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
8760: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8770: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
8780: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
8790: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
87a0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
87b0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
87c0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
87d0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
87e0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
87f0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8800: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8810: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8820: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8830: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8840: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8850: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
8860: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8870: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
8880: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
8890: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
88a0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
88b0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
88c0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
88d0: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
88e0: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
88f0: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
8900: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
8910: 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  d..** <ul>.** <l
8920: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8930: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20  _SIZE_HINT]].** 
8940: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8950: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
8960: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
8970: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
8980: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
8990: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
89a0: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
89b0: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
89c0: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
89d0: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
89e0: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
89f0: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
8a00: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
8a10: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
8a20: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
8a30: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
8a40: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
8a50: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
8a60: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
8a70: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
8a80: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
8a90: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
8aa0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
8ab0: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
8ac0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
8ad0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8ae0: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
8af0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
8b00: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
8b10: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
8b20: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
8b30: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
8b40: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
8b50: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
8b60: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
8b70: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
8b80: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
8b90: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
8ba0: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
8bb0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
8bc0: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
8bd0: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
8be0: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
8bf0: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
8c00: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
8c10: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
8c20: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
8c30: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
8c40: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
8c50: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
8c60: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
8c70: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
8c80: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
8c90: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
8ca0: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
8cb0: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
8cc0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8cd0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
8ce0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
8cf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
8d00: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
8d10: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
8d20: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
8d30: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
8d40: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
8d50: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
8d60: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
8d70: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
8d80: 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71  on.  See the [sq
8d90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8da0: 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74  ol()] documentat
8db0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  ion for.** addit
8dc0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
8dd0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
8de0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8df0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28  _OMITTED]].** ^(
8e00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8e10: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20  L_SYNC_OMITTED] 
8e20: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
8e30: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
8e40: 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  y.** SQLite and 
8e50: 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65  sent to all VFSe
8e60: 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20  s in place of a 
8e70: 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e  call to the xSyn
8e80: 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e  c method.** when
8e90: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
8ea0: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52  nnection has [PR
8eb0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8ec0: 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a  ] set to OFF.)^.
8ed0: 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69  ** Some speciali
8ee0: 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74  zed VFSes need t
8ef0: 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72  his signal in or
8f00: 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63  der to operate c
8f10: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e  orrectly.** when
8f20: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
8f30: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
8f40: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
8f50: 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20  s set, but most 
8f60: 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74  .** VFSes do not
8f70: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
8f80: 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c  l and should sil
8f90: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
8fa0: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70  s opcode..** App
8fb0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
8fc0: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
8fd0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8fe0: 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20  )] with this.** 
8ff0: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
9000: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
9010: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
9020: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9030: 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f  VFSes.** that do
9040: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9050: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9060: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9070: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
9080: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
9090: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
90a0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
90b0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
90c0: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
90d0: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
90e0: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
90f0: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
9100: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
9110: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
9120: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
9130: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
9140: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
9150: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
9160: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
9170: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
9180: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
9190: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
91a0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
91b0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
91c0: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
91d0: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
91e0: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
91f0: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
9200: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
9210: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
9220: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
9230: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
9240: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
9250: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
9260: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
9270: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
9280: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
9290: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
92a0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
92b0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
92c0: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
92d0: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
92e0: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
92f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9300: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
9310: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
9320: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
9330: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
9340: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
9350: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
9360: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
9370: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
9380: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
9390: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
93a0: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
93b0: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
93c0: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
93d0: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
93e0: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
93f0: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
9400: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
9410: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
9420: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
9430: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
9440: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
9450: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
9460: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
9470: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
9480: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
9490: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
94a0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
94b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
94c0: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
94d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
94e0: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
94f0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
9500: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
9510: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
9520: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
9530: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
9540: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
9550: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
9560: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
9570: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
9580: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
9590: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
95a0: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
95b0: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
95c0: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
95d0: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
95e0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
95f0: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
9600: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
9610: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
9620: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
9630: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
9640: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
9650: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
9660: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
9670: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
9680: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
9690: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
96a0: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
96b0: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
96c0: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
96d0: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
96e0: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
96f0: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
9700: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
9710: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
9720: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
9730: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
9740: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
9750: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9760: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9770: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9780: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9790: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
97a0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
97b0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
97c0: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
97d0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
97e0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
97f0: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
9800: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
9810: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
9820: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
9830: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
9840: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
9850: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
9860: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
9870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
9880: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
9890: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
98a0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
98b0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
98c0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
98d0: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
98e0: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
98f0: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
9900: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
9910: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
9920: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
9930: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
9940: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
9950: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
9960: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
9970: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
9980: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
9990: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
99a0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
99b0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
99c0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
99d0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
99e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
99f0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9a00: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9a10: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
9a20: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
9a30: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
9a40: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
9a50: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
9a60: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
9a70: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
9a80: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
9a90: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
9aa0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
9ab0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
9ac0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
9ad0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
9ae0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9af0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
9b00: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
9b10: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
9b20: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
9b30: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
9b40: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
9b50: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
9b60: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
9b70: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
9b80: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
9b90: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
9ba0: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
9bb0: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
9bc0: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
9bd0: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
9be0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9bf0: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
9c00: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9c10: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
9c20: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
9c30: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
9c40: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
9c50: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
9c60: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
9c70: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
9c80: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
9c90: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
9ca0: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
9cb0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
9cc0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
9cd0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
9ce0: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
9cf0: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
9d00: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
9d10: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
9d20: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
9d30: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
9d40: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
9d50: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
9d60: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
9d70: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
9d80: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
9d90: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
9da0: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
9db0: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
9dc0: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
9dd0: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
9de0: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
9df0: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
9e00: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
9e10: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
9e20: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
9e30: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
9e40: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
9e50: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
9e60: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
9e70: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
9e80: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
9e90: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
9ea0: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
9eb0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9ec0: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
9ed0: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
9ee0: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
9ef0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
9f00: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
9f10: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
9f20: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
9f30: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
9f40: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
9f50: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
9f60: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9f70: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
9f80: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
9f90: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
9fa0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
9fb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9fc0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
9fd0: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
9fe0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
9ff0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
a000: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
a010: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
a020: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
a030: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
a040: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
a050: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
a060: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
a070: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
a080: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
a090: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
a0a0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
a0b0: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
a0c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a0d0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a0e0: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
a0f0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
a100: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
a110: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
a120: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
a130: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
a140: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
a150: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
a160: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
a170: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
a180: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
a190: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
a1a0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
a1b0: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
a1c0: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
a1d0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
a1e0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a1f0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a200: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
a210: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
a220: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
a230: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
a240: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
a250: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a260: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
a270: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
a280: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
a290: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
a2a0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
a2b0: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
a2c0: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
a2d0: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
a2e0: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
a2f0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
a300: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ent.  ^If the [S
a310: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a320: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a330: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
a340: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
a350: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
a360: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
a370: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
a380: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
a390: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
a3a0: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
a3b0: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
a3c0: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
a3d0: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
a3e0: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
a3f0: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
a400: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a410: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
a420: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
a430: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
a440: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
a450: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
a460: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
a470: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
a480: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
a490: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
a4a0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a4b0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
a4c0: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 69 73 20 66  LER]].** ^This f
a4d0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20  ile-control may 
a4e0: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  be invoked by SQ
a4f0: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61  Lite on the data
a500: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  base file handle
a510: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65  .** shortly afte
a520: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69  r it is opened i
a530: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
a540: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  de a custom VFS 
a550: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74  with access.** t
a560: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  o the connection
a570: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  s busy-handler c
a580: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67  allback. The arg
a590: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65  ument is of type
a5a0: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20   (void **).** - 
a5b0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20  an array of two 
a5c0: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e  (void *) values.
a5d0: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64   The first (void
a5e0: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69   *) actually poi
a5f0: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63  nts.** to a func
a600: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e  tion of type (in
a610: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20  t (*)(void *)). 
a620: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f  In order to invo
a630: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ke the connectio
a640: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c  ns.** busy-handl
a650: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  er, this functio
a660: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f  n should be invo
a670: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63  ked with the sec
a680: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a  ond (void *) in.
a690: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20  ** the array as 
a6a0: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  the only argumen
a6b0: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  t. If it returns
a6c0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
a6d0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
a6e0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69   should be retri
a6f0: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  ed. If it return
a700: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74  s zero, the cust
a710: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62  om VFS should ab
a720: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72  andon the.** cur
a730: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a  rent operation..
a740: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a750: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
a760: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c  ENAME]].** ^Appl
a770: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f  ication can invo
a780: 6b 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  ke this file-con
a790: 74 72 6f 6c 20 74 6f 20 68 61 76 65 20 53 51 4c  trol to have SQL
a7a0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
a7b0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
a7c0: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
a7d0: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
a7e0: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
a7f0: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
a800: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
a810: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
a820: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
a830: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
a840: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
a850: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
a860: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
a870: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
a880: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
a890: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
a8a0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
a8b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
a8c0: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
a8d0: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
a8e0: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
a8f0: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
a900: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
a910: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  k..**.** </ul>.*
a920: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
a930: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
a940: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
a950: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a960: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
a970: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a  E             2.
a980: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
a990: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
a9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
a9b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
a9c0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
a9d0: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
a9e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a9f0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
aa00: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
aa10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
aa20: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
aa30: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
aa40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
aa50: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
aa60: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
aa70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
aa80: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
aa90: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
aaa0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
aab0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
aac0: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
aad0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
aae0: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
aaf0: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
ab00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
ab10: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
ab20: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
ab30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
ab40: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
ab50: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
ab60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
ab70: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
ab80: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
ab90: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
abb0: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
abc0: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
abd0: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
abe0: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
abf0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
ac00: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
ac10: 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  6../*.** CAPI3RE
ac20: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
ac30: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
ac40: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
ac50: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
ac60: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
ac70: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
ac80: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
ac90: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
aca0: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
acb0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
acc0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
acd0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
ace0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
acf0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
ad00: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
ad10: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
ad20: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
ad30: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
ad40: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
ad50: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
ad60: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
ad70: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
ad80: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
ad90: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
ada0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
adb0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
adc0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
add0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
ade0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
adf0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
ae00: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
ae10: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
ae20: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
ae30: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
ae40: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
ae50: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ae60: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
ae70: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
ae80: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
ae90: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
aea0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
aeb0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
aec0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
aed0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
aee0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
aef0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
af00: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
af10: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
af20: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
af30: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
af40: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
af50: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
af60: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
af70: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
af80: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
af90: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
afa0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
afb0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
afc0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
afd0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
afe0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
aff0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
b000: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
b010: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
b020: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
b030: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
b040: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
b050: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
b060: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
b070: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
b080: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
b090: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
b0a0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
b0b0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
b0c0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
b0d0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
b0e0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
b0f0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
b100: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
b110: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
b120: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
b130: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
b140: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
b150: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
b160: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
b170: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
b180: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
b190: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
b1a0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
b1b0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
b1c0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
b1d0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
b1e0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
b1f0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
b200: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
b210: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
b220: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
b230: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
b240: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
b250: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
b260: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
b270: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
b280: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
b290: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
b2a0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
b2b0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
b2c0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
b2d0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
b2e0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
b2f0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
b300: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
b310: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
b320: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
b330: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
b340: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
b350: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
b360: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
b370: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
b380: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
b390: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
b3a0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
b3b0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
b3c0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
b3d0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
b3e0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
b3f0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
b400: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
b410: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
b420: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
b430: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
b440: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
b450: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
b460: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
b470: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
b480: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
b490: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
b4a0: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
b4b0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
b4c0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
b4d0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
b4e0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
b4f0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
b500: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
b510: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
b520: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
b530: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
b540: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
b550: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
b560: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
b570: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
b580: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
b590: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
b5a0: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
b5b0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
b5c0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
b5d0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
b5e0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
b5f0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
b600: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
b610: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
b620: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
b630: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
b640: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
b650: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
b660: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
b670: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
b680: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
b690: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
b6a0: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
b6b0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
b6c0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
b6d0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
b6e0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
b6f0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
b700: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
b710: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
b720: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
b730: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
b740: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
b750: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
b760: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
b770: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
b780: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
b790: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
b7a0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
b7b0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
b7c0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
b7d0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
b7e0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
b7f0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
b800: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
b810: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
b820: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
b830: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
b840: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
b850: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
b860: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
b870: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
b880: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
b890: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
b8a0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
b8b0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
b8c0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
b8d0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
b8e0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
b8f0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
b900: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
b910: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
b920: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
b930: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
b940: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
b950: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
b960: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
b970: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
b980: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
b990: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
b9a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
b9b0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
b9c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
b9d0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
b9e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b9f0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
ba00: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ba10: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
ba20: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ba30: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
ba40: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
ba50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
ba60: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
ba70: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
ba80: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
ba90: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
baa0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
bab0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
bac0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
bad0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
bae0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
baf0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
bb00: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
bb10: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
bb20: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
bb30: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
bb40: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
bb50: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
bb60: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
bb70: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
bb80: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
bb90: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
bba0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
bbb0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
bbc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
bbd0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
bbe0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
bbf0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
bc00: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
bc10: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
bc20: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
bc30: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
bc40: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
bc50: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
bc60: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
bc70: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
bc80: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
bc90: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
bca0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
bcb0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
bcc0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
bcd0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
bce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
bcf0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
bd00: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
bd10: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
bd20: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
bd30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
bd40: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
bd50: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
bd60: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
bd70: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
bd80: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
bd90: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
bda0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
bdb0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
bdc0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
bdd0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
bde0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
bdf0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
be00: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
be10: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
be20: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
be30: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
be40: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
be50: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
be60: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
be70: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
be80: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
be90: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
bea0: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
beb0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
bec0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
bed0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
bee0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
bef0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
bf00: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
bf10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
bf20: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
bf30: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
bf40: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
bf50: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
bf60: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
bf70: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
bf80: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
bf90: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
bfa0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
bfb0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
bfc0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
bfd0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
bfe0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
bff0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
c000: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
c010: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
c020: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
c030: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
c040: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
c050: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
c060: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
c070: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
c080: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
c090: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
c0a0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
c0b0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
c0c0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
c0d0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
c0e0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
c0f0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
c100: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
c110: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
c120: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
c130: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
c140: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
c150: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
c160: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
c170: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
c180: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
c190: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
c1a0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
c1b0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
c1c0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
c1d0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
c1e0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
c1f0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
c200: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
c210: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
c220: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
c230: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
c240: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
c250: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
c260: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
c270: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
c280: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
c290: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
c2a0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
c2b0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
c2c0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
c2d0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
c2e0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
c2f0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
c300: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
c310: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
c320: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
c330: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
c340: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
c350: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
c360: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
c370: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
c380: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
c390: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
c3a0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
c3b0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
c3c0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
c3d0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
c3e0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
c3f0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
c400: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
c410: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
c420: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
c430: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
c440: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
c450: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
c460: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
c470: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
c480: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
c490: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
c4a0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
c4b0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
c4c0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
c4d0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
c4e0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
c4f0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
c500: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
c510: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
c520: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
c530: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
c540: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
c550: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
c560: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
c570: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
c580: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
c590: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
c5a0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
c5b0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
c5c0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
c5d0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
c5e0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
c5f0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
c600: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
c610: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
c620: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
c630: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
c640: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
c650: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
c660: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
c670: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
c680: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
c690: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
c6a0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
c6b0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
c6c0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
c6d0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
c6e0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
c6f0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
c700: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
c710: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
c720: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
c730: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
c740: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
c750: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
c760: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
c770: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
c780: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
c790: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
c7a0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
c7b0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
c7c0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
c7d0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
c7e0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
c7f0: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
c800: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
c810: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
c820: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
c830: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
c840: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
c850: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
c860: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
c870: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
c880: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
c890: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
c8a0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
c8b0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
c8c0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
c8d0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
c8e0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
c8f0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
c900: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
c910: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
c920: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
c930: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
c940: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
c950: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
c960: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
c970: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
c980: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
c990: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
c9a0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
c9b0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
c9c0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
c9d0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
c9e0: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
c9f0: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
ca00: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
ca10: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
ca20: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
ca30: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
ca40: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
ca50: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
ca60: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
ca70: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
ca80: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
ca90: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
caa0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
cab0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
cac0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
cad0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
cae0: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
caf0: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
cb00: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
cb10: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
cb20: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
cb30: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
cb40: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
cb50: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
cb60: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
cb70: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
cb80: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
cb90: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
cba0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
cbb0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
cbc0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
cbd0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
cbe0: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
cbf0: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
cc00: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
cc10: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
cc20: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
cc30: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
cc40: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
cc50: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
cc60: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
cc70: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
cc80: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
cc90: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
cca0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
ccb0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
ccc0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
ccd0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
cce0: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
ccf0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
cd00: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
cd10: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
cd20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
cd30: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
cd40: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
cd50: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
cd60: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
cd70: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
cd80: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
cd90: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
cda0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
cdb0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
cdc0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
cdd0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
cde0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
cdf0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
ce00: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
ce10: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
ce20: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
ce30: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
ce40: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ce50: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
ce60: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
ce70: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
ce80: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
ce90: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
cea0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
ceb0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
cec0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
ced0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
cee0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
cef0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
cf00: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
cf10: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
cf20: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
cf30: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
cf40: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
cf50: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
cf60: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
cf70: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
cf80: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
cf90: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
cfa0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
cfb0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
cfc0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
cfd0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
cfe0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
cff0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
d000: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
d010: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
d020: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
d030: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
d040: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
d050: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
d060: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
d070: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
d080: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
d090: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
d0a0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
d0b0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
d0c0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
d0d0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
d0e0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
d0f0: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
d100: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
d110: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
d120: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
d130: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
d140: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
d150: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
d160: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
d170: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
d180: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
d190: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
d1a0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
d1b0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
d1c0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
d1d0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
d1e0: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
d1f0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
d200: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
d210: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
d220: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
d230: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
d240: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
d250: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
d260: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
d270: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
d280: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d290: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d2a0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
d2b0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
d2c0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
d2d0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
d2e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d2f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d300: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
d310: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
d320: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
d330: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d340: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
d350: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
d360: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
d370: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
d380: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
d390: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
d3a0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
d3b0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
d3c0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
d3d0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
d3e0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
d3f0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
d400: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
d410: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d420: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
d430: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
d440: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
d450: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
d460: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
d470: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
d480: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
d490: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
d4a0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
d4b0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
d4c0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
d4d0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
d4e0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
d4f0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
d500: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
d510: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
d520: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
d530: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
d540: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
d550: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
d560: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
d570: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d580: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
d590: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
d5a0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
d5b0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
d5c0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
d5d0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
d5e0: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
d5f0: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
d600: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
d610: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
d620: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
d630: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
d640: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d650: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
d660: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
d670: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
d680: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
d690: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
d6a0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
d6b0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
d6c0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
d6d0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
d6e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
d6f0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
d700: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
d710: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
d720: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
d730: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
d740: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
d750: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
d760: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
d770: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
d780: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
d790: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
d7a0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
d7b0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
d7c0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
d7d0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
d7e0: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
d7f0: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
d800: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
d810: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
d820: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
d830: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
d840: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
d850: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
d860: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
d870: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
d880: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
d890: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
d8a0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
d8b0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
d8c0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
d8d0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
d8e0: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
d8f0: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
d900: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
d910: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
d920: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
d930: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
d940: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
d950: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d960: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
d970: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
d980: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
d990: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
d9a0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
d9b0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
d9c0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
d9d0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
d9e0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
d9f0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
da00: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
da10: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
da20: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
da30: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
da40: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
da50: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
da60: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
da70: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
da80: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
da90: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
daa0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
dab0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
dac0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
dad0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
dae0: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
daf0: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
db00: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
db10: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
db20: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
db30: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
db40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
db50: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
db60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
db70: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
db80: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
db90: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
dba0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
dbb0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
dbc0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
dbd0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
dbe0: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
dbf0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
dc00: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
dc10: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
dc20: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
dc30: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
dc40: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
dc50: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
dc60: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
dc70: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
dc80: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
dc90: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
dca0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
dcb0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
dcc0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
dcd0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
dce0: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
dcf0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
dd00: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
dd10: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
dd20: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
dd30: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
dd40: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
dd50: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
dd60: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
dd70: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
dd80: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
dd90: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
dda0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
ddb0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
ddc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ddd0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
dde0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
ddf0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
de00: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
de10: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
de20: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
de30: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
de40: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
de50: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
de60: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
de70: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
de80: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
de90: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
dea0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
deb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
dec0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
ded0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
dee0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
def0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
df00: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
df10: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
df20: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
df30: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
df40: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
df50: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
df60: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
df70: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
df80: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
df90: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
dfa0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
dfb0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
dfc0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
dfd0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
dfe0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
dff0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
e000: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
e010: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
e020: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
e030: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
e040: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
e050: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
e060: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
e070: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e080: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
e090: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
e0a0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
e0b0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
e0c0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
e0d0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
e0e0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
e0f0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
e100: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
e110: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e120: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
e130: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
e140: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
e150: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
e160: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
e170: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
e180: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
e190: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
e1a0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
e1b0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
e1c0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
e1d0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
e1e0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
e1f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e200: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
e210: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
e220: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
e230: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
e240: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
e250: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
e260: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e270: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
e280: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
e290: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e2a0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
e2b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
e2c0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
e2d0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
e2e0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
e2f0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
e300: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
e310: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e320: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
e330: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
e340: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
e350: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
e360: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
e370: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
e380: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
e390: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
e3a0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
e3b0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
e3c0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
e3d0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
e3e0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
e3f0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
e400: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
e410: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
e420: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
e430: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
e440: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
e450: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
e460: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
e470: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
e480: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
e490: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
e4a0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
e4b0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
e4c0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
e4d0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
e4e0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
e4f0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
e500: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e510: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
e520: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
e530: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
e540: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
e550: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
e560: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
e570: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
e580: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
e590: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
e5a0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
e5b0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
e5c0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
e5d0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
e5e0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
e5f0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
e600: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
e610: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e620: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
e630: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
e640: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
e650: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e660: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
e670: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
e680: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
e690: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
e6a0: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
e6b0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
e6c0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
e6d0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
e6e0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
e6f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
e700: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
e710: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
e720: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
e730: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
e740: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
e750: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
e760: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
e770: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
e780: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
e790: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
e7a0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
e7b0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
e7c0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
e7d0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
e7e0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
e7f0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
e800: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
e810: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
e820: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
e830: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
e840: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
e850: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
e860: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
e870: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
e880: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
e890: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
e8a0: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
e8b0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
e8c0: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
e8d0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
e8e0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
e8f0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
e900: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
e910: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
e920: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
e930: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
e940: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
e950: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
e960: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
e970: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
e980: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
e990: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
e9a0: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
e9b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
e9c0: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
e9d0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
e9e0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
e9f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ea00: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
ea10: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
ea20: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
ea30: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
ea40: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
ea50: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
ea60: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
ea70: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
ea80: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
ea90: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
eaa0: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
eab0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
eac0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
ead0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
eae0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
eaf0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
eb00: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
eb10: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
eb20: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
eb30: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
eb40: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
eb50: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
eb60: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
eb70: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
eb80: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
eb90: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
eba0: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
ebb0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
ebc0: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
ebd0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
ebe0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
ebf0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
ec00: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
ec10: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
ec20: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
ec30: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
ec40: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
ec50: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
ec60: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
ec70: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
ec80: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
ec90: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
eca0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
ecb0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
ecc0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
ecd0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
ece0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
ecf0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
ed00: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
ed10: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
ed20: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
ed30: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51  ialize(void);.SQ
ed40: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
ed50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
ed60: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
ed70: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  int sqlite3_os_i
ed80: 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nit(void);.SQLIT
ed90: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
eda0: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
edb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
edc0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
edd0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
ede0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
edf0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
ee00: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
ee10: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
ee20: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
ee30: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
ee40: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
ee50: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
ee60: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
ee70: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
ee80: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
ee90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
eea0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
eeb0: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
eec0: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
eed0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
eee0: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
eef0: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
ef00: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
ef10: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
ef20: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
ef30: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
ef40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
ef50: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
ef60: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
ef70: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
ef80: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
ef90: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
efa0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
efb0: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
efc0: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
efd0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
efe0: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
eff0: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
f000: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
f010: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
f020: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
f030: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
f040: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
f050: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
f060: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
f070: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
f080: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f090: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
f0a0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
f0b0: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
f0c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f0d0: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
f0e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
f0f0: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
f100: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
f110: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
f120: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
f130: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
f140: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
f150: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
f160: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
f170: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
f180: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
f190: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
f1a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
f1b0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
f1c0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
f1d0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
f1e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f1f0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
f200: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
f210: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
f220: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
f230: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
f240: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
f250: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
f260: 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
f270: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
f280: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
f290: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
f2a0: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
f2b0: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
f2c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f2d0: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
f2e0: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
f2f0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
f300: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
f310: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
f320: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
f330: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
f340: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
f350: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
f360: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
f370: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
f380: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
f390: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
f3a0: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
f3b0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
f3c0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
f3d0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
f3e0: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
f3f0: 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
f400: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
f410: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
f420: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
f430: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
f440: 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
f450: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
f460: 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
f470: 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
f480: 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
f490: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
f4a0: 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
f4b0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
f4c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
f4d0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
f4e0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f4f0: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
f500: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
f510: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
f520: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
f530: 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
f540: 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
f550: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
f560: 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
f570: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f580: 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
f590: 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
f5a0: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
f5b0: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
f5c0: 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
f5d0: 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
f5e0: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
f5f0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
f600: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
f610: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
f620: 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
f630: 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
f640: 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
f650: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
f660: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
f670: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
f680: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f690: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
f6a0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
f6b0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
f6c0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
f6d0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
f6e0: 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
f6f0: 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
f700: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
f710: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
f720: 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
f730: 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
f740: 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
f750: 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
f760: 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
f770: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
f780: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
f790: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
f7a0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
f7b0: 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
f7c0: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
f7d0: 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
f7e0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
f7f0: 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  OC] or [SQLITE_C
f800: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
f810: 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69  .  .** By creati
f820: 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
f830: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
f840: 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
f850: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
f860: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
f870: 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64  IG_MALLOC]).** d
f880: 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
f890: 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ion, an applicat
f8a0: 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
f8b0: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
f8c0: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
f8d0: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ion subsystem fo
f8e0: 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
f8f0: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a  for all of its.*
f900: 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  * dynamic memory
f910: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
f920: 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
f930: 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61  omes with severa
f940: 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  l [built-in memo
f950: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a  ry allocators].*
f960: 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65  * that are perfe
f970: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
f980: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
f990: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
f9a0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
f9b0: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
f9c0: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
f9d0: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
f9e0: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
f9f0: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
fa00: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
fa10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
fa20: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
fa30: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
fa40: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
fa50: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
fa60: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
fa70: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
fa80: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
fa90: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
faa0: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
fab0: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
fac0: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
fad0: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
fae0: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
faf0: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
fb00: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
fb10: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
fb20: 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63  Malloc, xRealloc
fb30: 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  , and xFree meth
fb40: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
fb50: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
fb60: 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
fb70: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
fb80: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
fb90: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
fba0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
fbb0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
fbc0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
fbd0: 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73  o.** xRealloc is
fbe0: 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20   always a value 
fbf0: 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72  returned by a pr
fc00: 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75  ior call to xRou
fc10: 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  ndup..**.** xSiz
fc20: 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
fc30: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
fc40: 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
fc50: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
fc60: 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
fc70: 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
fc80: 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
fc90: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
fca0: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
fcb0: 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
fcc0: 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
fcd0: 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
fce0: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
fcf0: 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
fd00: 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
fd10: 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
fd20: 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
fd30: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fd40: 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
fd50: 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
fd60: 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
fd70: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
fd80: 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
fd90: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
fda0: 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
fdb0: 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
fdc0: 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
fdd0: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
fde0: 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
fdf0: 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
fe00: 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
fe10: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
fe20: 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
fe30: 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
fe40: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
fe50: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
fe60: 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
fe70: 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
fe80: 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
fe90: 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
fea0: 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
feb0: 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
fec0: 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
fed0: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
fee0: 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
fef0: 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
ff00: 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f   allocator.  (Fo
ff10: 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
ff20: 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
ff30: 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
ff40: 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
ff50: 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
ff60: 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
ff70: 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
ff80: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
ff90: 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
ffa0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
ffb0: 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
ffc0: 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
ffd0: 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
ffe0: 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
fff0: 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
10000 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
10010 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
10020 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
10030 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
10040 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
10050 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
10060 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
10070 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
10080 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
10090 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
100a0 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
100b0 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
100c0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
100d0 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
100e0 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
100f0 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
10100 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
10110 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
10120 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
10130 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
10140 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
10150 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
10160 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10170 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10180 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
10190 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
101a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
101b0 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
101c0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
101d0 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
101e0 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
101f0 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
10200 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
10210 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
10220 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
10230 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
10240 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
10250 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
10260 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
10270 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
10280 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
10290 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
102a0 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
102b0 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
102c0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
102d0 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
102e0 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
102f0 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
10300 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
10310 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
10320 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
10330 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
10340 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
10350 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
10360 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
10370 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
10380 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
10390 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
103a0 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
103b0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
103c0 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
103d0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
103e0 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
103f0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
10400 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
10410 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
10420 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
10430 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
10440 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
10450 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
10460 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
10470 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
10480 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
10490 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
104a0 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
104b0 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
104c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
104d0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
104e0 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
104f0 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
10500 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
10510 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
10520 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
10530 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
10540 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
10550 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10560 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
10570 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
10580 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
10590 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
105a0 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
105b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
105c0 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
105d0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
105e0 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
105f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
10600 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
10610 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
10620 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
10630 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10640 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
10650 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
10660 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
10670 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
10680 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
10690 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
106a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
106b0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
106c0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
106d0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
106e0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
106f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10700 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
10710 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
10720 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
10730 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
10740 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
10750 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
10760 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
10770 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
10780 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
10790 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
107a0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
107b0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
107c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
107d0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
107e0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
107f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10800 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
10810 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
10820 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10830 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
10840 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10850 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
10860 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10870 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10880 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10890 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
108a0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
108b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
108c0 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
108d0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
108e0 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
108f0 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
10900 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
10910 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
10920 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
10930 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
10940 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
10950 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10960 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
10970 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
10980 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
10990 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
109a0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
109b0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
109c0 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
109d0 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
109e0 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
109f0 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
10a00 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
10a10 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
10a20 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
10a30 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
10a40 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
10a50 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
10a60 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
10a70 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
10a80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
10a90 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10aa0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
10ab0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
10ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
10ad0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
10ae0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
10af0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
10b00 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
10b10 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
10b20 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
10b30 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
10b40 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
10b50 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
10b60 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
10b70 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
10b80 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
10b90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
10ba0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
10bb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
10bc0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
10bd0 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
10be0 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
10bf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
10c00 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
10c10 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
10c20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
10c30 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
10c40 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
10c50 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
10c60 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
10c70 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
10c80 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
10c90 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
10ca0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
10cb0 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
10cc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
10cd0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
10ce0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
10cf0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
10d00 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
10d10 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
10d20 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
10d30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10d40 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
10d50 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
10d60 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
10d70 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
10d80 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
10d90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10da0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
10db0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
10dc0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
10dd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
10de0 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
10df0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
10e00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
10e20 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
10e30 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
10e40 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
10e50 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
10e60 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
10e70 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
10e80 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
10e90 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
10ea0 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
10eb0 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
10ec0 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
10ed0 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
10ee0 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
10ef0 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
10f00 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
10f10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10f20 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
10f30 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
10f40 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
10f50 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
10f60 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
10f70 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10f80 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
10f90 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
10fa0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10fb0 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
10fc0 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
10fd0 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
10fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
10ff0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11000 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
11010 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
11020 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
11030 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
11040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11050 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
11060 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11070 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
11080 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
11090 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
110a0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
110b0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
110c0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
110d0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
110e0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
110f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11100 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11110 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
11120 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
11130 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11140 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11150 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11160 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11170 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11180 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11190 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
111a0 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
111b0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
111c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
111d0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
111e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
111f0 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
11200 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11210 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11220 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11230 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11240 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
11250 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
11260 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
11270 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
11280 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
11290 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
112a0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
112b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
112c0 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
112d0 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
112e0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
112f0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
11300 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
11310 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
11320 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
11330 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
11340 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
11350 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11360 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
11370 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
11380 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11390 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
113a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
113b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
113c0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
113d0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
113e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
113f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11400 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11410 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11420 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11430 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
11440 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
11450 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
11460 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
11470 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
11480 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
11490 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
114a0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
114b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
114c0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
114d0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
114e0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
114f0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
11500 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11510 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
11520 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
11530 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
11540 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
11550 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
11560 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
11570 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
11580 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11590 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
115a0 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
115b0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
115c0 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
115d0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
115e0 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
115f0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
11600 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
11610 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
11620 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
11630 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
11640 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
11650 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
11660 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
11670 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
11680 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
11690 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68  are disabled, th
116a0 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  e .** following 
116b0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
116c0 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
116d0 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
116e0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
116f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
11700 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
11710 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
11720 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
11730 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
11740 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
11750 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
11760 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
11770 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
11780 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
11790 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
117a0 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
117b0 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
117c0 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
117d0 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
117e0 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
117f0 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
11800 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
11810 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
11820 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
11830 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
11840 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
11860 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
11870 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
11880 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11890 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
118a0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
118b0 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
118c0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
118d0 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  or.** scratch me
118e0 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65  mory.  There are
118f0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
11900 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20  :  A pointer an 
11910 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
11920 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  d memory buffer 
11930 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73  from which the s
11940 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
11950 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
11960 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
11970 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
11980 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
11990 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
119a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
119b0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
119c0 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
119d0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
119e0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
119f0 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
11a00 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
11a10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
11a20 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
11a30 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
11a40 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
11a50 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
11a60 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
11a70 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
11a80 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
11a90 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
11aa0 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
11ab0 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
11ac0 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
11ad0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
11ae0 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
11af0 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
11b00 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
11b10 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
11b20 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
11b30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
11b40 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
11b50 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
11b60 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
11b70 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
11b80 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
11b90 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
11ba0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11bb0 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
11bc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
11bd0 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
11be0 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
11bf0 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
11c00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11c10 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
11c20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11c30 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
11c40 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
11c50 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
11c60 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
11c70 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
11c80 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
11c90 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  * the database p
11ca0 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
11cb0 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20  he default page 
11cc0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
11cd0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
11ce0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
11cf0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
11d00 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
11d10 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
11d20 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
11d30 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
11d40 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54   using the SQLIT
11d50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
11d60 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72   option..** Ther
11d70 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11d80 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11d90 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20  tion: A pointer 
11da0 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  to 8-byte aligne
11db0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
11dc0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
11dd0 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
11de0 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
11df0 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
11e00 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
11e10 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
11e20 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
11e30 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
11e40 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
11e50 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
11e60 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61  nd 32768) plus a
11e70 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f   little extra fo
11e80 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
11e90 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67  eader.  ^The pag
11ea0 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73  e header size is
11eb0 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20   20 to 40 bytes 
11ec0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20  depending on.** 
11ed0 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65  the host archite
11ee0 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68  cture.  ^It is h
11ef0 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
11f00 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
11f10 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
11f20 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
11f30 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
11f40 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
11f50 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
11f60 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
11f70 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
11f80 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
11f90 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
11fa0 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
11fb0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
11fc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
11fd0 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
11fe0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
11ff0 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
12000 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
12010 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61  to cache.  ^If a
12020 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
12030 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
12040 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
12050 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
12060 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
12070 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
12080 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
12090 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
120a0 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
120b0 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
120c0 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
120d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
120e0 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
120f0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
12100 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
12110 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
12120 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
12130 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
12140 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12150 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
12160 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
12170 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
12180 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12190 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
121a0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
121b0 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
121c0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
121d0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
121e0 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
121f0 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
12200 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
12210 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
12220 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12230 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
12240 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12250 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
12260 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
12270 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
12280 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
12290 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
122a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
122b0 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
122c0 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
122d0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
122e0 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
122f0 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
12300 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
12310 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
12320 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
12330 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
12340 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
12350 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
12360 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
12370 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
12380 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
12390 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
123a0 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
123b0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
123c0 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
123d0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
123e0 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
123f0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
12400 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
12410 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
12420 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
12430 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
12440 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
12450 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
12460 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
12470 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
12480 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12490 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
124a0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
124b0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
124c0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
124d0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
124e0 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
124f0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
12500 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
12510 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
12520 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
12530 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
12540 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
12550 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
12560 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
12570 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
12580 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
12590 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
125a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
125b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
125c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
125d0 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
125e0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
125f0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12600 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12610 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12620 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12630 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12640 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
12650 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12660 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
12670 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
12680 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
12690 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
126a0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
126b0 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
126c0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
126d0 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
126e0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
126f0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65   of the.** conte
12700 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12710 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
12720 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
12730 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
12740 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12750 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
12760 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12770 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
12780 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
12790 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
127a0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
127b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
127c0 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
127d0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
127e0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
127f0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
12800 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
12810 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
12820 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
12830 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12840 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
12850 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
12860 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
12870 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
12880 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12890 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
128a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
128b0 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
128c0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
128d0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
128e0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
128f0 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12900 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12910 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12920 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
12930 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
12950 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
12960 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
12970 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
12980 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
12990 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
129a0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
129b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
129c0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
129d0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
129e0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
129f0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
12a00 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
12a10 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
12a20 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
12a30 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
12a40 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
12a50 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12a60 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12a70 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12a80 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12a90 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12aa0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12ab0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
12ac0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
12ad0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
12ae0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
12af0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
12b00 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
12b10 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
12b20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12b30 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
12b40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
12b50 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
12b60 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
12b70 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12b80 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
12b90 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
12ba0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
12bb0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
12bc0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12bd0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
12be0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
12bf0 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d  the default.** m
12c00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12c10 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69   for the lookasi
12c20 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
12c30 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b  tor on each.** [
12c40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12c50 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ion].  The first
12c60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
12c70 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
12c80 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
12c90 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
12ca0 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
12cb0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
12cc0 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
12cd0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
12ce0 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73  ction.)^  ^(This
12cf0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12d00 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  .** <i>default</
12d10 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
12d20 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
12d30 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12d40 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73  E].** verb to [s
12d50 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12d60 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
12d70 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
12d80 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
12d90 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
12da0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
12db0 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
12dc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12dd0 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
12de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12df0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
12e00 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12e10 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12e20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12e30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
12e40 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
12e50 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
12e60 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
12e70 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
12e80 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
12e90 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
12ea0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12eb0 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
12ec0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
12ed0 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
12ee0 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
12ef0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
12f00 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
12f10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12f20 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
12f30 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
12f40 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
12f50 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
12f60 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
12f70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12f80 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12f90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12fa0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
12fb0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
12fc0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
12fd0 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
12fe0 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
12ff0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
13000 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
13010 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
13020 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
13030 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
13040 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
13050 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13060 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
13070 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
13080 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
13090 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
130a0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
130b0 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
130c0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
130d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
130e0 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
130f0 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
13100 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
13110 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
13120 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
13130 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
13140 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
13150 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
13160 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
13170 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
13180 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
13190 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
131a0 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
131b0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
131c0 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
131d0 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
131e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
131f0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
13200 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
13210 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
13220 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
13230 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
13240 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
13250 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
13260 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
13270 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
13280 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13290 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
132a0 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
132b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
132c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
132d0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
132e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
132f0 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
13300 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
13310 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
13320 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
13330 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
13340 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
13350 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
13360 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
13370 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
13380 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
13390 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
133a0 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
133b0 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
133c0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
133d0 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
133e0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
133f0 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
13400 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
13410 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
13420 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
13430 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
13440 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
13450 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
13460 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
13470 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
13480 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
13490 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
134a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
134b0 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
134c0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
134d0 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69  * <dd> This opti
134e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
134f0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
13500 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a  pe int. If non-z
13510 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49  ero, then.** URI
13520 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13530 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49  bally enabled. I
13540 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
13550 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  is zero, then UR
13560 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73  I handling.** is
13570 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
13580 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c  ed. If URI handl
13590 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
135a0 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
135b0 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64  enames.** passed
135c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
135d0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
135e0 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  pen_v2()], [sqli
135f0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
13600 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
13610 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
13620 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
13630 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
13640 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
13650 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
13660 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
13670 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
13680 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
13690 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
136a0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
136b0 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c   If it is global
136c0 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
136d0 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
136e0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
136f0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
13700 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
13710 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
13720 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
13730 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
13740 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c  ned. By default,
13750 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
13760 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
13770 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
13780 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
13790 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
137a0 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
137b0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
137c0 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
137d0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
137e0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
137f0 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
13800 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13810 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
13820 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  CAN.** <dd> This
13830 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13840 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61  single integer a
13850 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13860 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a   interpreted as.
13870 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  ** a boolean in 
13880 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
13890 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  or disable the u
138a0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
138b0 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75  ndices for.** fu
138c0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
138d0 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
138e0 6d 69 7a 65 72 2e 20 20 54 68 65 20 64 65 66 61  mizer.  The defa
138f0 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
13900 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
13910 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
13920 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
13930 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
13940 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
13950 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
13960 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
13970 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
13980 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
13990 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
139a0 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
139b0 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
139c0 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
139d0 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
139e0 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
139f0 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
13a00 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
13a10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75  unction.** malfu
13a20 6e 63 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  nction when the 
13a30 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
13a40 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
13a50 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
13a60 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
13a70 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
13a80 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
13a90 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
13aa0 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
13ab0 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
13ac0 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
13ad0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
13ae0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
13af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13b00 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
13b10 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
13b20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
13b30 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
13b40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13b50 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
13b60 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
13b70 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
13b80 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
13b90 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
13ba0 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
13bb0 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
13bc0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
13bd0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
13be0 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  ops..** </dl>.**
13bf0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13c00 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
13c10 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13c20 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
13c30 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
13c40 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
13c50 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
13c60 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
13c70 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
13c80 4c 4c 4f 47 20 70 72 65 2d 70 72 6f 63 65 73 73  LLOG pre-process
13c90 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
13ca0 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
13cb0 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
13cc0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
13cd0 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
13ce0 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
13cf0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
13d00 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
13d10 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
13d20 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
13d30 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
13d40 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
13d50 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
13d60 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
13d70 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
13d80 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
13d90 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
13da0 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
13db0 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
13dc0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
13dd0 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
13de0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13df0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
13e00 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
13e10 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
13e20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
13e30 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
13e40 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
13e50 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
13e60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
13e70 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
13e80 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
13e90 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
13ea0 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
13eb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
13ec0 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
13ed0 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
13ee0 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
13ef0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
13f00 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
13f10 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
13f20 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
13f30 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
13f40 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
13f50 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
13f60 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
13f70 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
13f80 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
13f90 49 6e 20 74 68 69 73 20 63 61 73 65 2e 0a 2a 2a  In this case..**
13fa0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
13fb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13fc0 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
13fd0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
13fe0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13ff0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
14000 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
14010 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14020 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
14030 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
14040 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14050 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
14060 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
14070 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
14080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14090 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
140a0 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
140b0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
140c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
140d0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
140e0 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
140f0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
14100 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14110 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14120 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
14130 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
14140 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
14150 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
14160 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
14170 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
14180 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
14190 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
141a0 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
141b0 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
141c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
141d0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
141e0 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
141f0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14200 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14210 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14220 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
14230 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14240 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
14250 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
14260 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
14270 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
14280 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
14290 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
142a0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
142b0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
142c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
142d0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
142e0 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
142f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14300 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14310 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
14320 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
14330 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14340 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
14350 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
14360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14370 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
14380 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
14390 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
143a0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
143b0 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
143c0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
143d0 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
143e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
143f0 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
14400 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
14410 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
14420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14430 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14440 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
14450 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
14460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14470 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
14480 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
14490 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
144a0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
144b0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
144c0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
144d0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
144e0 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
144f0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
14500 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14510 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
14520 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
14530 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14540 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
14550 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
14560 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
14570 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
14580 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
14590 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
145a0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
145b0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
145c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
145d0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
145e0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
145f0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
14600 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
14610 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
14620 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14630 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
14640 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
14650 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
14660 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
14670 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
14680 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
14690 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
146a0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
146b0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
146c0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
146d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
146e0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
146f0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
14700 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
14710 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
14720 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
14730 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
14740 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
14750 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
14760 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
14770 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
14780 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
14790 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
147a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
147b0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
147c0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
147d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
147e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
147f0 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
14800 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
14810 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
14820 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
14830 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
14840 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14850 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
14860 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
14870 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
14880 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
14890 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
148a0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
148b0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
148c0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
148d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
148e0 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
148f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
14900 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
14910 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
14920 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
14930 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
14940 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
14950 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
14960 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
14970 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
14980 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
14990 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
149a0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
149b0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
149c0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
149d0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
149e0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
149f0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
14a00 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
14a10 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
14a20 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
14a30 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14a40 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
14a50 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
14a60 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
14a70 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
14a80 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
14a90 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
14aa0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
14ab0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
14ac0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
14ad0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
14ae0 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
14af0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
14b00 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
14b10 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
14b20 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
14b30 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
14b40 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
14b50 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
14b60 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
14b70 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
14b80 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
14b90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14ba0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
14bb0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
14bc0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
14bd0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
14be0 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
14bf0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
14c00 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
14c10 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
14c20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
14c30 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
14c40 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
14c50 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
14c60 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
14c70 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
14c80 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
14c90 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
14ca0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
14cb0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
14cc0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
14cd0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
14ce0 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
14cf0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
14d00 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
14d10 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
14d20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
14d30 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
14d40 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
14d50 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
14d60 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
14d70 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
14d80 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
14d90 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
14da0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
14db0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
14dc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
14dd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14de0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
14df0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
14e00 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
14e10 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
14e20 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
14e30 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
14e40 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
14e50 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
14e60 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
14e70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
14e80 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
14e90 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
14ea0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
14eb0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
14ec0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
14ed0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
14ee0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
14ef0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14f00 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
14f10 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
14f20 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
14f30 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
14f40 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
14f50 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
14f60 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
14f70 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
14f80 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
14f90 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
14fa0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
14fb0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
14fc0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
14fd0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
14fe0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
14ff0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
15000 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
15010 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
15020 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
15030 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
15040 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
15050 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
15060 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
15070 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
15080 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
15090 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
150a0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
150b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
150c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
150d0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
150e0 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
150f0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
15100 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
15110 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
15120 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15130 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
15140 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
15150 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
15160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
15170 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
15180 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
15190 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
151a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
151b0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
151c0 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
151d0 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
151e0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
151f0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
15200 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
15210 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
15220 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
15230 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
15240 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
15250 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
15260 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
15270 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
15280 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
15290 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
152a0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
152b0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
152c0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
152d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
152e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
152f0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
15300 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
15310 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
15320 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
15330 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
15340 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e  rt Rowid.**.** ^
15350 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
15360 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
15370 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
15380 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
15390 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
153a0 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
153b0 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
153c0 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
153d0 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
153e0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
153f0 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
15400 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
15410 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
15420 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
15430 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
15440 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
15450 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
15460 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
15470 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
15480 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
15490 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
154a0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
154b0 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
154c0 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
154d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
154e0 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
154f0 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
15500 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ent.** successfu
15510 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
15520 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
15530 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  m the [database 
15540 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69  connection].** i
15550 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
15560 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51  ment.  ^As of SQ
15570 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
15580 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .7, this routine
15590 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65  s.** records the
155a0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77   last insert row
155b0 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e  id of both ordin
155c0 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b  ary tables and [
155d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
155e0 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
155f0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a  ssful [INSERT]s.
15600 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
15610 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61  urred on that da
15620 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15630 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
15640 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ned..**.** ^(If 
15650 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
15660 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
15670 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
15680 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
15690 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
156a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
156b0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
156c0 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
156d0 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
156e0 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
156f0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
15700 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
15710 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
15720 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
15730 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
15740 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
15750 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
15760 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
15770 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
15780 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
15790 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
157a0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
157b0 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
157c0 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
157d0 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
157e0 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
157f0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
15800 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
15810 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
15820 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
15830 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
15840 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
15850 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
15860 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
15870 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
15880 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
15890 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
158a0 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
158b0 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
158c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
158d0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
158e0 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
158f0 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
15900 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
15910 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
15920 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
15930 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
15940 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
15950 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
15960 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
15970 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
15980 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
15990 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
159a0 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
159b0 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
159c0 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
159d0 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
159e0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
159f0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
15a00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
15a10 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
15a20 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
15a30 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
15a40 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
15a50 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
15a60 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
15a70 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
15a80 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
15a90 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
15aa0 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
15ab0 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
15ac0 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
15ad0 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
15ae0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
15af0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
15b00 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
15b10 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
15b20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
15b30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
15b40 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
15b50 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
15b60 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
15b70 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
15b80 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
15b90 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
15ba0 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
15bb0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
15bc0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
15bd0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
15be0 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
15bf0 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
15c00 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
15c10 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
15c20 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
15c30 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51  t [rowid]..*/.SQ
15c40 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
15c50 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
15c60 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
15c70 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
15c80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
15c90 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
15ca0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
15cb0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
15cc0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
15cd0 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
15ce0 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
15cf0 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
15d00 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
15d10 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
15d20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
15d30 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
15d40 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
15d50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15d60 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
15d70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15d80 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
15d90 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
15da0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
15db0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
15dc0 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
15dd0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
15de0 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
15df0 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
15e00 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
15e10 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
15e20 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
15e30 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
15e40 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
15e50 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
15e60 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
15e70 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
15e80 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
15e90 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
15ea0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
15eb0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
15ec0 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
15ed0 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
15ee0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
15ef0 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
15f00 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
15f10 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
15f20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
15f30 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
15f40 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
15f50 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
15f60 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
15f70 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
15f80 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
15f90 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
15fa0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
15fb0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
15fc0 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
15fd0 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
15fe0 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
15ff0 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
16000 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
16010 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
16020 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
16030 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
16040 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
16050 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
16060 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
16070 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
16080 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
16090 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
160a0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
160b0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
160c0 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
160d0 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
160e0 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
160f0 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
16100 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
16110 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
16120 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
16130 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
16140 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
16150 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
16160 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
16170 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
16180 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
16190 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
161a0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
161b0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
161c0 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
161d0 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
161e0 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
161f0 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
16200 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
16210 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
16220 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
16230 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
16240 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
16250 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
16260 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
16270 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
16280 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
16290 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
162a0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
162b0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
162c0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
162d0 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
162e0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
162f0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
16300 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
16310 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
16320 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
16330 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
16340 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
16350 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
16360 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
16370 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
16380 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
16390 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
163a0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
163b0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
163c0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
163d0 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
163e0 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
163f0 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
16400 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
16410 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
16420 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
16430 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
16440 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
16450 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
16460 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
16470 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
16480 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
16490 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
164a0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
164b0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
164c0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
164d0 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
164e0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
164f0 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
16500 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
16510 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
16520 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
16530 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
16540 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
16550 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
16560 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
16570 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
16580 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
16590 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
165a0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
165b0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
165c0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
165d0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
165e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
165f0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
16600 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
16610 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
16620 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
16630 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
16640 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
16650 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
16660 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
16670 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
16680 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
16690 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
166a0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
166b0 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
166c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
166d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
166e0 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
166f0 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52  caused by [INSER
16700 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20  T],.** [UPDATE] 
16710 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
16720 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
16730 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16740 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
16750 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e  d..** ^(The coun
16760 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  t returned by sq
16770 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
16780 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61  ges() includes a
16790 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72  ll changes.** fr
167a0 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54  om all [CREATE T
167b0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
167c0 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63  ] contexts and c
167d0 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a  hanges made by.*
167e0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
167f0 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72  ctions]. However
16800 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64  ,.** the count d
16810 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
16820 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20  changes used to 
16830 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41  implement [REPLA
16840 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  CE] constraints,
16850 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
16860 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
16870 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54  sing, or [DROP T
16880 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67  ABLE] processing
16890 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20  .  The.** count 
168a0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
168b0 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74   rows of views t
168c0 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53  hat fire an [INS
168d0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
168e0 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74  ,.** though if t
168f0 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  he INSTEAD OF tr
16900 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e  igger makes chan
16910 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20  ges of its own, 
16920 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a  those changes .*
16930 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e  * are counted.)^
16940 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
16950 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
16960 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73   function counts
16970 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20   the changes as 
16980 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73  soon as.** the s
16990 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
169a0 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70  kes them is comp
169b0 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
169c0 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
169d0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f  .** is passed to
169e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
169f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
16a00 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
16a10 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
16a20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
16a30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
16a40 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
16a50 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
16a60 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
16a70 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
16a80 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
16a90 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
16aa0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
16ab0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
16ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
16ad0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
16ae0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
16af0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
16b00 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
16b10 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
16b20 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
16b30 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
16b40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
16b50 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
16b60 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
16b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16b80 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
16b90 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
16ba0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
16bb0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
16bc0 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
16bd0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
16be0 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
16bf0 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
16c00 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
16c10 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
16c20 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
16c30 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
16c40 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
16c50 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
16c60 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
16c70 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
16c80 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
16c90 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
16ca0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
16cb0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
16cc0 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
16cd0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
16ce0 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
16cf0 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
16d00 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
16d10 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
16d20 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
16d30 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
16d40 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
16d50 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
16d60 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
16d70 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
16d80 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
16d90 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
16da0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
16db0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16dc0 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
16dd0 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
16de0 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
16df0 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
16e00 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
16e10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
16e20 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
16e30 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
16e40 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
16e50 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
16e60 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
16e70 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
16e80 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
16e90 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
16ea0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
16eb0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
16ec0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
16ed0 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
16ee0 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
16ef0 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
16f00 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
16f10 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
16f20 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
16f30 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
16f40 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
16f50 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
16f60 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
16f70 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
16f80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
16f90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
16fa0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
16fb0 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
16fc0 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
16fd0 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
16fe0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
16ff0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17000 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
17010 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
17020 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
17030 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
17040 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
17050 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
17060 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
17070 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
17080 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
17090 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
170a0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
170b0 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
170c0 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
170d0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
170e0 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
170f0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
17100 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
17110 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
17120 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
17130 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
17140 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
17150 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
17160 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17170 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
17180 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
17190 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
171a0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
171b0 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
171c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
171d0 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
171e0 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
171f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
17200 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
17210 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
17220 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
17230 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
17240 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
17250 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
17260 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
17270 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17280 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
17290 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
172a0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
172b0 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
172c0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  I void sqlite3_i
172d0 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
172e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
172f0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
17300 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
17310 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
17320 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
17330 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
17340 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
17350 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
17360 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
17370 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
17380 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
17390 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
173a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
173b0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
173c0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
173d0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
173e0 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
173f0 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
17400 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
17410 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
17420 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
17430 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
17440 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
17450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
17460 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
17470 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
17480 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
17490 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
174a0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
174b0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
174c0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
174d0 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
174e0 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
174f0 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
17500 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
17510 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
17520 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
17530 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
17540 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
17550 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
17560 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
17570 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
17580 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
17590 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
175a0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
175b0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
175c0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
175d0 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
175e0 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
175f0 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
17600 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
17610 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
17620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
17630 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
17640 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
17650 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
17660 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
17670 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
17680 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
17690 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
176a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
176b0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
176c0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
176d0 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
176e0 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
176f0 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
17700 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
17710 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
17720 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
17730 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
17740 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
17750 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
17760 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
17770 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
17780 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
17790 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
177a0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
177b0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
177c0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
177d0 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
177e0 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
177f0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
17800 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
17810 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
17820 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
17830 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
17840 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
17850 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
17860 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
17870 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
17880 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
17890 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
178a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
178b0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
178c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
178d0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
178e0 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
178f0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
17900 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
17910 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
17920 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
17930 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
17940 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
17950 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
17960 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
17970 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
17980 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
17990 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
179a0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
179b0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
179c0 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
179d0 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54   Errors.**.** ^T
179e0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
179f0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
17a00 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
17a10 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
17a20 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
17a30 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
17a40 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
17a50 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
17a60 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
17a70 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
17a80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
17a90 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
17aa0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
17ab0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
17ac0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
17ad0 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
17ae0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
17af0 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
17b00 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
17b10 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
17b20 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
17b30 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
17b40 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
17b50 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
17b60 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
17b70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17b80 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
17b90 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
17ba0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
17bb0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
17bc0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
17bd0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
17be0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
17bf0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
17c00 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
17c10 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
17c20 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
17c30 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
17c40 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
17c50 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
17c60 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
17c70 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
17c80 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
17c90 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
17ca0 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
17cb0 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
17cc0 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
17cd0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
17ce0 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
17cf0 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
17d00 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
17d10 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
17d20 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
17d30 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
17d40 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
17d50 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
17d60 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
17d70 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
17d80 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
17d90 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
17da0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
17db0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
17dc0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
17dd0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
17de0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
17df0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
17e00 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
17e10 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
17e20 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
17e30 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
17e40 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
17e50 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
17e60 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
17e70 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
17e80 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b  TE_BUSY].** or [
17e90 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
17ea0 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
17eb0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
17ec0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
17ed0 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
17ee0 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
17ef0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
17f00 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
17f10 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
17f20 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
17f30 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
17f40 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
17f50 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
17f60 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
17f70 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
17f80 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
17f90 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
17fa0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
17fb0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
17fc0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
17fd0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
17fe0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
17ff0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
18000 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
18010 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
18020 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
18030 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
18040 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
18050 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
18060 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
18070 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
18080 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
18090 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
180a0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
180b0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
180c0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
180d0 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
180e0 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
180f0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
18100 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
18110 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
18120 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
18130 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
18140 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
18150 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
18160 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
18170 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
18180 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
18190 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
181a0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
181b0 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
181c0 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
181d0 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
181e0 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
181f0 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
18200 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
18210 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
18220 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
18230 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
18240 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
18250 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
18260 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
18270 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
18280 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
18290 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
182a0 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
182b0 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
182c0 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
182d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
182e0 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
182f0 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
18300 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73  ders.  ^If it is
18310 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
18320 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
18330 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
18340 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
18350 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
18360 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
18370 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
18380 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
18390 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
183a0 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
183b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
183c0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
183d0 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
183e0 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69  _BLOCKED].  ^Thi
183f0 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
18400 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
18410 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
18420 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
18430 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
18440 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
18450 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
18460 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
18470 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
18480 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
18490 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
184a0 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
184b0 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
184c0 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
184d0 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  rtant..**.** ^(T
184e0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
184f0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
18500 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
18510 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
18520 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18530 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
18540 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
18550 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
18560 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
18570 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
18580 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
18590 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
185a0 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20  )].** will also 
185b0 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65  set or clear the
185c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
185d0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
185e0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
185f0 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
18600 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
18610 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
18620 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
18630 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
18640 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73   handler.  Any s
18650 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
18660 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
18670 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
18680 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
18690 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
186a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
186b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
186c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
186d0 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
186e0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
186f0 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
18700 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  I int sqlite3_bu
18710 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
18720 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
18730 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
18740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18750 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
18760 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
18770 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
18780 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
18790 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
187a0 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
187b0 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
187c0 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
187d0 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
187e0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
187f0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
18800 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
18810 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
18820 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
18830 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
18840 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
18850 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
18860 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
18870 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
18880 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
18890 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
188a0 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
188b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
188c0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
188d0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
188e0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
188f0 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
18900 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
18910 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
18920 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
18930 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
18940 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
18950 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
18960 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
18970 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
18980 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
18990 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
189a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
189b0 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
189c0 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
189d0 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
189e0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
189f0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
18a00 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
18a10 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
18a20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
18a30 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
18a40 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
18a50 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
18a60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
18a70 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
18a80 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
18a90 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
18aa0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
18ab0 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
18ac0 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
18ad0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
18ae0 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
18af0 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
18b00 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
18b10 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
18b20 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
18b30 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
18b40 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
18b50 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
18b60 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
18b70 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
18b80 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
18b90 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
18ba0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
18bb0 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
18bc0 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
18bd0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
18be0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
18bf0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
18c00 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
18c10 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
18c20 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
18c30 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
18c40 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
18c50 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
18c60 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
18c70 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
18c80 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
18c90 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
18ca0 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
18cb0 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
18cc0 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
18cd0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
18ce0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
18cf0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
18d00 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
18d10 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
18d20 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
18d30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
18d40 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
18d50 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
18d60 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
18d70 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
18d80 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
18d90 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
18da0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
18db0 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
18dc0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
18dd0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
18de0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
18df0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
18e00 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
18e10 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
18e20 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
18e30 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
18e40 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
18e50 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
18e60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
18e70 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
18e80 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
18e90 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
18ea0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
18eb0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
18ec0 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
18ed0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
18ee0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
18ef0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
18f00 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
18f10 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
18f20 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
18f30 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
18f40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
18f50 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
18f60 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
18f70 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
18f80 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
18f90 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
18fa0 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
18fb0 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
18fc0 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
18fd0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
18fe0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
18ff0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
19000 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
19010 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
19020 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19030 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
19040 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
19050 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
19060 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
19070 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
19080 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
19090 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
190a0 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
190b0 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
190c0 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
190d0 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
190e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
190f0 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
19100 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
19110 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
19120 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
19130 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
19140 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
19150 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
19160 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19170 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
19180 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19190 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
191a0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
191b0 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
191c0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
191d0 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
191e0 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
191f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
19200 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
19210 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
19220 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
19230 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19240 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
19250 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19260 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
19270 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
19280 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
19290 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
192a0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
192b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
192c0 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
192d0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
192e0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
192f0 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
19300 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
19310 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
19320 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
19330 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
19340 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
19350 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
19360 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
19370 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
19380 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
19390 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
193a0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
193b0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
193c0 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
193d0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
193e0 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
193f0 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
19400 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
19410 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
19420 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
19430 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
19440 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
19450 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
19460 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
19470 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
19480 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
19490 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
194a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
194b0 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
194c0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
194d0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
194e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
194f0 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
19500 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
19510 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
19520 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
19530 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
19540 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
19550 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
19560 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
19570 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
19580 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
19590 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
195a0 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
195b0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
195c0 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
195d0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
195e0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
195f0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
19600 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
19610 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
19620 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
19630 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
19640 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
19650 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
19660 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
19670 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
19680 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
19690 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
196a0 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
196b0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
196c0 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
196d0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
196e0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
196f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
19700 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  rmsg()]..*/.SQLI
19710 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
19720 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
19730 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
19740 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
19750 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
19760 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
19770 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
19780 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
19790 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
197a0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
197b0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
197c0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
197d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
197e0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
197f0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
19800 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
19810 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
19820 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
19830 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
19840 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
19850 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
19860 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
19870 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53  ten here */.);.S
19880 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
19890 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
198a0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
198b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
198c0 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
198d0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
198e0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
198f0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
19900 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
19910 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
19920 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
19930 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
19940 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
19950 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
19960 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
19970 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
19980 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
19990 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
199a0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
199b0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
199c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
199d0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
199e0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
199f0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
19a00 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
19a10 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
19a20 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
19a30 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
19a40 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
19a50 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
19a60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
19a70 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
19a80 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
19a90 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
19aa0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
19ab0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
19ac0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
19ad0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
19ae0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
19af0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
19b00 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
19b10 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
19b20 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
19b30 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
19b40 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
19b50 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
19b60 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
19b70 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
19b80 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
19b90 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
19ba0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
19bb0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
19bc0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
19bd0 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
19be0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
19bf0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
19c00 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
19c10 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
19c20 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
19c30 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
19c40 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
19c50 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
19c60 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
19c70 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
19c80 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
19c90 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
19ca0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
19cb0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
19cc0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
19cd0 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
19ce0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
19cf0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
19d00 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
19d10 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
19d20 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
19d30 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
19d40 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
19d50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
19d60 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
19d70 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
19d80 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
19d90 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
19da0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
19db0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
19dc0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
19dd0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
19de0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
19df0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
19e00 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
19e10 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
19e20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
19e30 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
19e40 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
19e50 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
19e60 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
19e70 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
19e80 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
19e90 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
19ea0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
19eb0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
19ec0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
19ed0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
19ee0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
19ef0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
19f00 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
19f10 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
19f20 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
19f30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
19f40 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
19f50 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
19f60 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
19f70 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
19f80 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
19f90 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
19fa0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
19fb0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
19fc0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
19fd0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
19fe0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
19ff0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1a000 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
1a010 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1a020 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1a030 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1a040 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1a050 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1a060 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1a070 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1a080 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1a090 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1a0a0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1a0b0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1a0c0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1a0d0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1a0e0 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1a0f0 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1a100 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1a110 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1a120 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1a130 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1a140 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1a150 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1a160 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1a170 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1a180 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1a190 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1a1a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a1b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1a1c0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1a1d0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1a1e0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1a1f0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1a200 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1a210 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1a220 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1a230 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1a240 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1a250 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1a260 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1a270 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1a280 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1a290 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1a2a0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1a2b0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1a2c0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1a2d0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1a2e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1a2f0 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1a300 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1a310 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1a320 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1a330 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1a340 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1a350 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1a360 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a370 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a380 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1a390 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1a3a0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1a3b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a3c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1a3d0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1a3e0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1a3f0 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1a400 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1a410 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1a420 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1a430 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a440 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1a450 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1a460 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1a470 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1a480 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a490 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1a4a0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1a4b0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1a4c0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1a4d0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1a4e0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1a4f0 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1a500 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1a510 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1a520 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1a530 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1a540 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1a550 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1a560 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1a570 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1a580 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1a590 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1a5a0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1a5b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1a5c0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1a5d0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1a5e0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1a5f0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1a600 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1a610 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1a620 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1a630 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1a640 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1a650 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1a660 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1a670 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1a680 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1a690 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1a6a0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1a6b0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1a6c0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1a6d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1a6e0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1a6f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1a700 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1a710 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1a720 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1a730 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1a740 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1a750 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1a760 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1a770 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1a780 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1a790 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1a7a0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1a7b0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1a7c0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1a7d0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1a7e0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1a7f0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1a800 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1a810 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1a820 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1a830 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51   string.)^.*/.SQ
1a840 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1a850 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1a860 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1a870 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1a880 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
1a890 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
1a8a0 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45  va_list);.SQLITE
1a8b0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1a8c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
1a8d0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1a8e0 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  *, ...);.SQLITE_
1a8f0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1a900 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
1a910 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1a920 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
1a930 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1a940 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
1a950 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
1a960 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
1a970 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
1a980 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
1a990 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
1a9a0 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
1a9b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
1a9c0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
1a9d0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
1a9e0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
1a9f0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
1aa00 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
1aa10 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1aa20 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
1aa30 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
1aa40 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
1aa50 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
1aa60 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
1aa70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1aa80 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
1aa90 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1aaa0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
1aab0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
1aac0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
1aad0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
1aae0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
1aaf0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1ab00 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
1ab10 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
1ab20 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
1ab30 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
1ab40 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1ab50 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
1ab60 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
1ab70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1ab80 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
1ab90 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
1aba0 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
1abb0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1abc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1abd0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1abe0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1abf0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1ac00 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1ac10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1ac20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ac30 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1ac40 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1ac50 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1ac60 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1ac70 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1ac80 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1ac90 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1aca0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1acb0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1acc0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1acd0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1ace0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1acf0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1ad00 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1ad10 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1ad20 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1ad30 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1ad40 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1ad50 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1ad60 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1ad70 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1ad80 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1ad90 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1ada0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1adb0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1adc0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1add0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1ade0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1adf0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1ae00 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1ae10 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1ae20 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1ae30 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1ae40 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1ae50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1ae60 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1ae70 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
1ae80 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1ae90 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1aea0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1aeb0 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
1aec0 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
1aed0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
1aee0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1aef0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
1af00 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
1af10 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
1af20 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1af30 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
1af40 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1af50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1af60 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1af70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1af80 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1af90 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1afa0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1afb0 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
1afc0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1afd0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1afe0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
1aff0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
1b000 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1b010 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
1b020 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1b030 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1b040 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1b050 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1b060 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1b070 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
1b080 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
1b090 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1b0a0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1b0b0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1b0c0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
1b0d0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1b0e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1b0f0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1b100 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1b110 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
1b120 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
1b130 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1b140 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1b150 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1b160 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1b170 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1b180 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1b190 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1b1a0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1b1b0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1b1c0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1b1d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
1b1e0 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
1b1f0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
1b200 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1b210 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
1b220 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
1b230 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1b240 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
1b250 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
1b260 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1b270 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1b280 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
1b290 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
1b2a0 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1b2b0 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1b2c0 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1b2d0 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1b2e0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1b2f0 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1b300 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1b310 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1b320 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1b330 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1b340 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1b350 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1b360 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1b370 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1b380 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1b390 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1b3a0 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1b3b0 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1b3c0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1b3d0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1b3e0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1b3f0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1b400 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1b410 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1b420 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1b430 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1b440 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1b450 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1b460 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1b470 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1b480 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1b490 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1b4a0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1b4b0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1b4c0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1b4d0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1b4e0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1b4f0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1b500 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1b510 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1b520 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1b530 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1b540 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1b550 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1b560 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1b570 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1b580 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1b590 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1b5a0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1b5b0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1b5c0 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1b5d0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1b5e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1b5f0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1b600 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b610 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1b620 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1b630 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1b640 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1b650 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1b660 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1b670 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1b680 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1b690 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b6a0 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1b6b0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1b6c0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1b6d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1b6e0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1b6f0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1b700 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1b710 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1b720 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1b730 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1b740 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1b750 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1b760 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1b770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1b780 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54  lloc(int);.SQLIT
1b790 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1b7a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1b7b0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
1b7c0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1b7d0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
1b7e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1b7f0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1b800 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1b810 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1b820 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1b830 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1b840 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1b850 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1b860 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1b870 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1b880 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1b890 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1b8a0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1b8b0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1b8c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1b8d0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1b8e0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1b8f0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1b900 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1b910 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1b920 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1b930 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1b940 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1b950 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1b960 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1b970 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1b980 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1b990 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1b9a0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1b9b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1b9c0 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1b9d0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1b9e0 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1b9f0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1ba00 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1ba10 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1ba20 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1ba30 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1ba40 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1ba50 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1ba60 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1ba70 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1ba80 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1ba90 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1baa0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1bab0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1bac0 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1bad0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1bae0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1baf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1bb00 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1bb10 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1bb20 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1bb30 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1bb40 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1bb50 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1bb60 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1bb70 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1bb80 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1bb90 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1bba0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1bbb0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1bbc0 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1bbd0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1bbe0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1bbf0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1bc00 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1bc10 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  reset..*/.SQLITE
1bc20 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
1bc30 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1bc40 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51  y_used(void);.SQ
1bc50 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1bc60 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1bc70 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1bc80 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
1bc90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bca0 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
1bcb0 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a  umber Generator.
1bcc0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
1bcd0 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
1bce0 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
1bcf0 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
1bd00 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
1bd10 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
1bd20 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57  dom [ROWID | ROW
1bd30 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74  IDs] when insert
1bd40 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
1bd50 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
1bd60 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
1bd70 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
1bd80 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20  ssible [ROWID]. 
1bd90 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
1bda0 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
1bdb0 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
1bdc0 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
1bdd0 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
1bde0 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
1bdf0 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
1be00 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
1be10 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
1be20 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
1be30 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  poses..**.** ^A 
1be40 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1be50 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
1be60 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
1be70 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
1be80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1be90 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
1bea0 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  ine is invoked (
1beb0 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c  either internall
1bec0 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61  y or by.** the a
1bed0 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20  pplication) the 
1bee0 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75  PRNG is seeded u
1bef0 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
1bf00 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
1bf10 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1bf20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
1bf30 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1bf40 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
1bf50 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ^On all subseque
1bf60 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
1bf70 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
1bf80 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
1bf90 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
1bfa0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
1bfb0 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
1bfc0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
1bfd0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
1bfe0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1bff0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
1c000 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
1c010 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
1c020 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1c030 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
1c040 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
1c050 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1c060 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1c070 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c080 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1c090 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1c0a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1c0b0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1c0c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1c0d0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1c0e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1c0f0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1c100 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1c110 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1c120 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1c130 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1c140 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1c150 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1c160 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c170 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1c180 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1c190 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1c1a0 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1c1b0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1c1c0 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1c1d0 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1c1e0 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1c1f0 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1c200 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1c210 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1c220 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1c230 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1c240 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1c250 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1c260 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1c270 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1c280 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1c290 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1c2a0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1c2b0 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1c2c0 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1c2d0 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1c2e0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1c2f0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1c300 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1c310 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1c320 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1c330 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1c340 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1c350 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1c360 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1c370 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1c380 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1c390 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1c3a0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1c3b0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1c3c0 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1c3d0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1c3e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1c3f0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1c400 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1c410 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1c420 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1c430 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1c440 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1c450 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1c460 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1c470 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1c480 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1c490 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1c4a0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1c4b0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1c4c0 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1c4d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c4e0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1c4f0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1c500 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1c510 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1c520 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1c530 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1c540 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1c550 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1c560 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1c570 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c580 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1c590 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1c5a0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1c5b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1c5c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1c5d0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1c5e0 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1c5f0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1c600 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1c610 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1c620 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1c630 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1c640 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1c650 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1c660 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1c670 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1c680 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1c690 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1c6a0 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1c6b0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1c6c0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1c6d0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1c6e0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1c6f0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1c700 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1c710 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1c720 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1c730 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1c740 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1c750 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1c760 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1c770 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c780 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1c790 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1c7a0 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1c7b0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1c7c0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1c7d0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1c7e0 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1c7f0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1c800 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1c810 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1c820 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1c830 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1c840 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1c850 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1c860 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1c870 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1c880 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1c890 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1c8a0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1c8b0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1c8c0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1c8d0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1c8e0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1c8f0 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1c900 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1c910 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1c920 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1c930 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1c940 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1c950 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1c960 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1c970 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1c980 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1c990 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1c9a0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1c9b0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1c9c0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1c9d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1c9e0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1c9f0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1ca00 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1ca10 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1ca20 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1ca30 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1ca40 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1ca50 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1ca60 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1ca70 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1ca80 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1ca90 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1caa0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1cab0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1cac0 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1cad0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1cae0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1caf0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1cb00 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1cb10 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1cb20 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1cb30 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1cb40 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1cb50 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1cb60 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1cb70 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1cb80 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1cb90 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1cba0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1cbb0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1cbc0 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1cbd0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1cbe0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1cbf0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1cc00 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1cc10 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1cc20 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1cc30 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1cc40 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1cc50 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1cc60 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1cc70 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1cc80 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1cc90 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1cca0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1ccb0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1ccc0 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1ccd0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1cce0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1ccf0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1cd00 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1cd10 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1cd20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cd30 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1cd40 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1cd50 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1cd60 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1cd70 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1cd80 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1cd90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1cda0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1cdb0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1cdc0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1cdd0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1cde0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1cdf0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ce00 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1ce10 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1ce20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1ce30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ce40 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1ce50 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1ce60 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1ce70 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1ce80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1ce90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1cea0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1ceb0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1cec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1ced0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1cee0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1cef0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1cf00 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1cf10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1cf20 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1cf30 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1cf40 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1cf50 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1cf60 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1cf70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1cf80 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1cf90 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1cfa0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1cfb0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1cfc0 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1cfd0 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1cfe0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1cff0 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1d000 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1d010 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1d020 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1d030 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d040 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1d050 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1d060 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1d070 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1d080 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1d090 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1d0a0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1d0b0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1d0c0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1d0d0 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1d0e0 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1d0f0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1d100 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1d110 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1d120 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d130 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1d140 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1d150 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1d160 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1d170 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1d180 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1d190 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1d1a0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1d1b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1d1c0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1d1d0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1d1e0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1d1f0 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1d200 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1d210 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1d220 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1d230 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1d240 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1d250 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1d260 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1d270 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1d280 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1d290 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1d2a0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1d2b0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1d2c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1d2d0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1d2e0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1d2f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1d300 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1d310 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1d320 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1d330 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1d340 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1d350 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1d360 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1d370 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52  d as a [SQLITE_R
1d380 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e  OLLBACK | return
1d390 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74   code].** from t
1d3a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1d3b0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1d3c0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1d3d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1d3e0 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1d3f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1d400 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1d410 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d420 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1d430 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1d440 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1d450 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1d460 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1d470 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1d480 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1d490 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1d4a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1d4b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1d4c0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1d4d0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1d4e0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1d4f0 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1d500 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1d510 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1d520 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1d530 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1d540 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1d550 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1d560 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1d570 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1d580 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1d590 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1d5a0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1d5b0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1d5c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1d5d0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1d5e0 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1d5f0 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1d600 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1d610 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1d620 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1d630 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1d640 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1d650 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1d660 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1d670 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1d680 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1d690 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1d6a0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1d6b0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1d6c0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1d6d0 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1d6e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1d6f0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1d700 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1d710 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1d720 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1d730 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1d740 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
1d750 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
1d760 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1d770 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d780 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
1d790 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1d7a0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1d7b0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1d7c0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
1d7d0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1d7e0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1d7f0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1d800 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1d810 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
1d820 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
1d830 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d840 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d850 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
1d860 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
1d870 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
1d880 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
1d890 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
1d8a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1d8b0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1d8c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d8d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
1d8e0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
1d8f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1d900 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1d910 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d920 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1d930 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
1d940 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1d950 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1d960 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d970 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1d980 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
1d990 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1d9a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d9b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d9c0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1d9d0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
1d9e0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1d9f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1da00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1da10 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
1da20 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
1da30 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1da40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1da50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1da60 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
1da70 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
1da80 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1da90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1daa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dab0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
1dac0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
1dad0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1dae0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1daf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1db00 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
1db10 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
1db20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1db30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1db40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1db50 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
1db60 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
1db70 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1db80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1db90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1dba0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
1dbb0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
1dbc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1dbd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1dbe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1dbf0 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
1dc00 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
1dc10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1dc20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1dc30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1dc40 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1dc50 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
1dc60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1dc70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1dc80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1dc90 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
1dca0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
1dcb0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1dcc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1dcd0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1dce0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
1dcf0 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
1dd00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1dd10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1dd20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
1dd30 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
1dd40 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1dd50 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1dd60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1dd70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
1dd80 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
1dd90 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1dda0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ddb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ddc0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
1ddd0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
1dde0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1ddf0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1de00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1de10 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
1de20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
1de30 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
1de40 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
1de50 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
1de60 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
1de70 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
1de80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1de90 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1dea0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1deb0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
1dec0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
1ded0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1dee0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1def0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1df00 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
1df10 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
1df20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1df30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1df40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1df50 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
1df60 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
1df70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1df80 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1df90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dfa0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
1dfb0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
1dfc0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
1dfd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1dfe0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dff0 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
1e000 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
1e010 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
1e020 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1e040 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
1e050 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
1e060 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
1e070 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1e080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1e090 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1e0a0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
1e0b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1e0c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e0d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
1e0e0 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
1e0f0 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
1e100 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e110 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e120 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1e130 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
1e140 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
1e150 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1e160 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1e170 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e180 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
1e190 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
1e1a0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1e1b0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1e1c0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
1e1d0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
1e1e0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1e1f0 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
1e200 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
1e210 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
1e220 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
1e230 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1e240 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
1e250 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
1e260 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
1e270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
1e280 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
1e290 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
1e2a0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
1e2b0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
1e2c0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1e2d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
1e2e0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
1e2f0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
1e300 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
1e310 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
1e320 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
1e330 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
1e340 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
1e350 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1e360 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1e370 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
1e380 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
1e390 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
1e3a0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
1e3b0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
1e3c0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
1e3d0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
1e3e0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
1e3f0 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
1e400 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
1e410 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1e420 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
1e430 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
1e440 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1e450 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1e460 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
1e470 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
1e480 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
1e490 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
1e4a0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
1e4b0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
1e4c0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
1e4d0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
1e4e0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
1e4f0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
1e500 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
1e510 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
1e520 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1e530 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1e540 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1e550 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1e560 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1e570 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1e580 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
1e590 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1e5a0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1e5b0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1e5c0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1e5d0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1e5e0 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1e5f0 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1e600 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1e610 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
1e620 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
1e630 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
1e640 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
1e650 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
1e660 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
1e670 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
1e680 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
1e690 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
1e6a0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
1e6b0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
1e6c0 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
1e6d0 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
1e6e0 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
1e6f0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1e700 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
1e710 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
1e720 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
1e730 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
1e740 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
1e750 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
1e760 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
1e770 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1e780 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
1e790 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
1e7a0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1e7b0 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
1e7c0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
1e7d0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1e7e0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1e7f0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1e800 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1e810 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
1e820 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1e830 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
1e840 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
1e850 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
1e860 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1e870 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
1e880 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1e890 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
1e8a0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
1e8b0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
1e8c0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1e8d0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
1e8e0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1e8f0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
1e900 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
1e910 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
1e920 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1e930 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
1e940 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1e950 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1e960 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
1e970 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1e980 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
1e990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1e9a0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
1e9b0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1e9c0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1e9d0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1e9e0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1e9f0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
1ea00 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
1ea10 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1ea20 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
1ea30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
1ea40 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1ea50 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
1ea60 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
1ea70 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1ea80 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1ea90 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1eaa0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1eab0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1eac0 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1ead0 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1eae0 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  k X..**.** ^Only
1eaf0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1eb00 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1eb10 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1eb20 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1eb30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1eb40 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1eb50 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1eb60 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1eb70 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1eb80 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1eb90 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1eba0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1ebb0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1ebc0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1ebd0 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1ebe0 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1ebf0 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1ec00 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1ec10 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1ec20 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ec30 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1ec40 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1ec50 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1ec60 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1ec70 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1ec80 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1ec90 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1eca0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1ecb0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1ecc0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1ecd0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1ece0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1ecf0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1ed00 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1ed10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1ed20 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1ed30 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1ed40 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1ed50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ed60 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ed70 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1ed80 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1ed90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1eda0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1edb0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1edc0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1edd0 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .**.*/.SQLITE_AP
1ede0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  I void sqlite3_p
1edf0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1ee00 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
1ee10 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1ee20 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1ee30 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
1ee40 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
1ee50 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
1ee60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1ee70 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1ee80 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
1ee90 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1eea0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1eeb0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1eec0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1eed0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1eee0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1eef0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1ef00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ef10 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1ef20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1ef30 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1ef40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ef50 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1ef60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1ef70 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1ef80 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1ef90 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1efa0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1efb0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1efc0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1efd0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1efe0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1eff0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1f000 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1f010 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1f020 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1f030 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1f040 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1f050 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1f060 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1f070 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1f080 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1f090 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1f0a0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1f0b0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1f0c0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1f0d0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1f0e0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1f0f0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1f100 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1f110 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1f120 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1f130 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1f140 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1f150 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1f160 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1f170 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1f180 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1f190 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1f1a0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1f1b0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1f1c0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1f1d0 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1f1e0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1f1f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1f200 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1f210 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1f220 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1f230 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1f240 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1f250 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1f260 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1f270 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1f280 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1f290 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1f2a0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1f2b0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1f2c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1f2d0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1f2e0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1f2f0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1f300 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1f310 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1f320 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1f330 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1f340 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1f350 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1f360 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1f370 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1f380 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1f390 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1f3a0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1f3b0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1f3c0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1f3d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1f3e0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1f3f0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1f400 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1f410 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1f420 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1f430 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1f440 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1f450 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1f460 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1f470 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1f480 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1f490 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1f4a0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
1f4b0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1f4c0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
1f4d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
1f4e0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
1f4f0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
1f500 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1f510 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1f520 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1f530 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1f540 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1f550 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1f560 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1f570 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1f580 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1f590 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1f5a0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1f5b0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
1f5c0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1f5d0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1f5e0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1f5f0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1f600 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
1f610 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
1f620 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1f630 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1f640 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
1f650 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
1f660 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
1f670 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1f680 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
1f690 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1f6a0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1f6b0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1f6c0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1f6d0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1f6e0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1f6f0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1f700 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1f710 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1f720 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
1f730 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1f740 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1f750 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1f760 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1f770 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1f780 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1f790 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1f7a0 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1f7b0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1f7c0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1f7d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f7e0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1f7f0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1f800 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1f810 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1f820 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
1f830 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1f840 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
1f850 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
1f860 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1f870 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1f880 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1f890 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1f8a0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1f8b0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1f8c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1f8d0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1f8e0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1f8f0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1f900 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1f910 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1f920 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1f930 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1f940 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1f950 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1f960 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1f970 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1f980 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1f990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1f9a0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1f9b0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1f9c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1f9d0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1f9e0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1f9f0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1fa00 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1fa10 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1fa20 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1fa30 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1fa40 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1fa50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fa60 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1fa70 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1fa80 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1fa90 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1faa0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1fab0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1fac0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1fad0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1fae0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1faf0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1fb00 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1fb10 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1fb20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1fb30 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1fb40 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1fb50 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1fb60 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1fb70 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1fb80 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
1fb90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1fba0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
1fbb0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
1fbc0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1fbd0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
1fbe0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
1fbf0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
1fc00 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
1fc10 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1fc20 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
1fc30 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
1fc40 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1fc50 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1fc60 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1fc70 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1fc80 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1fc90 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1fca0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1fcb0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1fcc0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1fcd0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1fce0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1fcf0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1fd00 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1fd10 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1fd20 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1fd30 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1fd40 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1fd50 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1fd60 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1fd70 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1fd80 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1fd90 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1fda0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1fdb0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1fdc0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1fdd0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1fde0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1fdf0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1fe00 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1fe10 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1fe20 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1fe30 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1fe40 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1fe50 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1fe60 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1fe70 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1fe80 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1fe90 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1fea0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1feb0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1fec0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1fed0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1fee0 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1fef0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1ff00 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1ff10 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1ff20 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1ff30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1ff40 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
1ff50 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
1ff60 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
1ff70 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
1ff80 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
1ff90 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
1ffa0 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
1ffb0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
1ffc0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
1ffd0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
1ffe0 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
1fff0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
20000 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
20010 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
20020 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
20030 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
20040 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
20050 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
20060 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
20070 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
20080 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
20090 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
200a0 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
200b0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
200c0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
200d0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
200e0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
200f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
20100 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
20110 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
20120 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
20130 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
20140 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
20150 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
20160 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
20170 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
20180 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
20190 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
201a0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
201b0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
201c0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
201d0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
201e0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
201f0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
20200 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
20210 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
20220 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
20230 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
20240 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
20250 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
20260 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
20270 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
20280 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
20290 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
202a0 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
202b0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
202c0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
202d0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
202e0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
202f0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
20300 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
20310 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
20320 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
20330 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
20340 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
20350 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
20360 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
20370 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
20380 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
20390 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
203a0 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
203b0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
203c0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
203d0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
203e0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
203f0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
20400 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
20410 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
20420 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
20430 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
20440 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
20450 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
20460 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
20470 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
20480 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
20490 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
204a0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
204b0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
204c0 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
204d0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
204e0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
204f0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
20500 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
20510 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
20520 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
20530 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
20540 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
20550 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
20560 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
20570 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
20580 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
20590 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
205a0 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
205b0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
205c0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
205d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
205e0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
205f0 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
20600 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
20610 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
20620 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
20630 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
20640 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
20650 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
20660 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
20670 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
20680 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
20690 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
206a0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
206b0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
206c0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
206d0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
206e0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
206f0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
20700 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
20710 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
20720 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
20730 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
20740 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
20750 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
20760 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
20770 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
20780 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
20790 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
207a0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
207b0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
207c0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
207d0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
207e0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
207f0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
20800 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
20810 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
20820 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
20830 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
20840 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
20850 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
20860 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
20870 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
20880 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
20890 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
208a0 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
208b0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
208c0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
208d0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
208e0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
208f0 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
20900 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
20910 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
20920 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
20930 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
20940 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
20950 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
20960 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
20970 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
20980 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
20990 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
209a0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
209b0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
209c0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
209d0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
209e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
209f0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
20a00 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
20a10 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
20a20 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
20a30 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
20a40 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
20a50 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
20a60 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
20a70 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
20a80 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
20a90 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
20aa0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
20ab0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
20ac0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
20ad0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
20ae0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
20af0 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
20b00 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
20b10 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
20b20 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
20b30 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
20b40 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
20b50 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
20b60 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
20b70 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
20b80 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
20b90 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
20ba0 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
20bb0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
20bc0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
20bd0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
20be0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
20bf0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
20c00 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
20c10 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
20c20 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
20c30 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
20c40 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
20c50 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
20c60 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
20c70 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
20c80 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
20c90 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
20ca0 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
20cb0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
20cc0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
20cd0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
20ce0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
20cf0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
20d00 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
20d10 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
20d20 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
20d30 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
20d40 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
20d50 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20d60 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
20d70 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
20d80 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
20d90 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
20da0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
20db0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
20dc0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
20dd0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
20de0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75  des any behaviou
20df0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
20e00 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
20e10 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20e20 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
20e30 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
20e40 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  E flag..** </ul>
20e50 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
20e60 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
20e70 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
20e80 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
20e90 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
20ea0 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
20eb0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
20ec0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
20ed0 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
20ee0 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
20ef0 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
20f00 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
20f10 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
20f20 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
20f30 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
20f40 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
20f50 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
20f60 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
20f70 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
20f80 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
20f90 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
20fa0 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
20fb0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
20fc0 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
20fd0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
20fe0 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
20ff0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
21000 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
21010 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
21020 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
21030 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
21040 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
21050 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
21060 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
21070 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
21080 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
21090 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
210a0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
210b0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
210c0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
210d0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
210e0 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
210f0 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
21100 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
21110 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
21120 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
21130 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
21140 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
21150 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
21160 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
21170 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
21180 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
21190 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
211a0 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
211b0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
211c0 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
211d0 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
211e0 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
211f0 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
21200 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
21210 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
21220 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
21230 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
21240 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
21250 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
21260 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
21270 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
21280 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
21290 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
212a0 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
212b0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
212c0 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
212d0 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
212e0 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
212f0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
21300 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
21310 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
21320 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
21330 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
21340 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
21350 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
21360 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
21370 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
21380 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
21390 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
213a0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
213b0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
213c0 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
213d0 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
213e0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
213f0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21400 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63  b?vfs=unix-noloc
21410 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  k <td>.**       
21420 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
21430 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21440 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
21450 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c  al VFS "unix-nol
21460 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ock"..** <tr><td
21470 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
21480 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
21490 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
214a0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
214b0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
214c0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
214d0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
214e0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
214f0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
21500 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
21510 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
21520 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
21530 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
21540 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
21550 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
21560 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
21570 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
21580 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
21590 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
215a0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
215b0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
215c0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
215d0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
215e0 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
215f0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
21600 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
21610 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
21620 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
21630 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
21640 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
21650 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
21660 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
21670 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
21680 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
21690 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
216a0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
216b0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
216c0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
216d0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
216e0 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
216f0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
21700 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
21710 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
21720 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
21730 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
21740 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
21750 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
21760 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
21770 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21780 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
21790 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
217a0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
217b0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
217c0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
217d0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
217e0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
217f0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
21800 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
21810 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
21820 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
21830 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
21840 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
21850 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
21860 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
21870 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
21880 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
21890 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
218a0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
218b0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
218c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
218d0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
218e0 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
218f0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
21900 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
21910 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
21920 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
21930 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
21940 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
21950 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
21960 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
21970 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
21980 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
21990 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
219a0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
219b0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
219c0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
219d0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
219e0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
219f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
21a00 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
21a10 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
21a20 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
21a30 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
21a40 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
21a50 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
21a60 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
21a70 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
21a80 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
21a90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
21aa0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
21ab0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
21ac0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
21ad0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
21ae0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
21af0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
21b00 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
21b10 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
21b20 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
21b30 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
21b40 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
21b50 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
21b60 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
21b70 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
21b80 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
21b90 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
21ba0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
21bb0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
21bc0 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
21bd0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
21be0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
21bf0 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
21c00 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
21c10 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
21c20 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
21c30 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
21c40 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
21c50 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
21c60 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
21c70 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
21c80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
21c90 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
21ca0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
21cb0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
21cc0 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
21cd0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
21ce0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
21cf0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
21d00 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
21d10 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
21d20 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
21d30 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
21d40 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
21d50 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
21d60 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
21d70 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
21d80 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
21d90 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
21da0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
21db0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
21dc0 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
21dd0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
21de0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
21df0 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
21e00 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
21e10 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
21e20 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
21e30 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
21e40 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
21e50 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
21e60 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
21e70 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
21e80 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
21e90 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
21ea0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
21eb0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
21ec0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
21ed0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
21ee0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
21ef0 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
21f00 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
21f10 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
21f20 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
21f30 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
21f40 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
21f50 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
21f60 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
21f70 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
21f80 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
21f90 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
21fa0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
21fb0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
21fc0 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
21fd0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
21fe0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
21ff0 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
22000 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
22010 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
22020 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
22030 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
22040 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
22050 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22060 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
22070 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
22080 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
22090 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
220a0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
220b0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
220c0 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
220d0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
220e0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
220f0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
22100 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
22110 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
22120 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
22130 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
22140 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
22150 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
22160 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
22170 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
22180 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
22190 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
221a0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
221b0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
221c0 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
221d0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
221e0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
221f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
22200 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
22210 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
22220 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
22230 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
22240 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
22250 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
22260 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
22270 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
22280 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
22290 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
222a0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
222b0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
222c0 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
222d0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
222e0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
222f0 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
22300 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
22310 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
22320 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
22330 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
22340 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
22350 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
22360 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
22370 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
22380 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
22390 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
223a0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
223b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
223c0 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
223d0 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54   *zParam);.SQLIT
223e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
223f0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
22400 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
22410 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
22420 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
22430 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  t);.SQLITE_API s
22440 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
22450 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
22460 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
22470 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
22480 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
22490 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
224a0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
224b0 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
224c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
224d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
224e0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
224f0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
22500 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
22510 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
22520 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
22530 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
22540 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
22550 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
22560 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22570 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
22580 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
22590 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
225a0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
225b0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
225c0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
225d0 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
225e0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
225f0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
22600 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
22610 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
22620 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
22630 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
22640 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
22650 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
22660 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
22670 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
22680 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
22690 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
226a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
226b0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
226c0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
226d0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
226e0 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
226f0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
22700 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
22710 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
22720 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
22730 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
22740 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
22750 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
22760 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
22770 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
22780 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
22790 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
227a0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
227b0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
227c0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
227d0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
227e0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
227f0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
22800 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
22810 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
22820 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
22830 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ons.)^.**.** ^Th
22840 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  e sqlite3_errstr
22850 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
22860 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68  urns the English
22870 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a  -language text.*
22880 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  * that describes
22890 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64   the [result cod
228a0 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  e], as UTF-8..**
228b0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
228c0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
228d0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
228e0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
228f0 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74  .** and must not
22900 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65   be freed by the
22910 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a   application)^..
22920 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
22930 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
22940 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
22950 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
22960 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
22970 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
22980 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
22990 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
229a0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
229b0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
229c0 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
229d0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
229e0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
229f0 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
22a00 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
22a10 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
22a20 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
22a30 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
22a40 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
22a50 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
22a60 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
22a70 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
22a80 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
22a90 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
22aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
22ab0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
22ac0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
22ad0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
22ae0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
22af0 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
22b00 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
22b10 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
22b20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
22b30 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
22b40 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
22b50 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
22b60 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
22b70 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
22b80 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
22b90 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
22ba0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
22bb0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
22bc0 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
22bd0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
22be0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
22bf0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
22c00 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
22c10 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
22c20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
22c30 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
22c40 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54  be set..*/.SQLIT
22c50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
22c60 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
22c70 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
22c80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
22c90 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
22ca0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51  sqlite3 *db);.SQ
22cb0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
22cc0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
22cd0 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  msg(sqlite3*);.S
22ce0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
22cf0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
22d00 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
22d10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
22d20 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
22d30 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
22d40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
22d50 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
22d60 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
22d70 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
22d80 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
22d90 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
22da0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
22db0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
22dc0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
22dd0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
22de0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
22df0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
22e00 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
22e10 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
22e20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
22e30 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
22e40 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
22e50 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
22e60 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
22e70 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
22e80 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
22e90 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
22ea0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
22eb0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
22ec0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
22ed0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
22ee0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
22ef0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
22f00 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
22f10 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
22f20 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
22f30 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
22f40 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
22f50 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
22f60 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
22f70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22f80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
22f90 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
22fa0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
22fb0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
22fc0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
22fd0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
22fe0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
22ff0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
23000 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
23010 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
23020 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
23030 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
23040 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
23050 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
23060 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
23070 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
23080 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
23090 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
230a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
230b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
230c0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
230d0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
230e0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
230f0 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
23100 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
23110 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
23120 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
23130 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
23140 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
23150 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
23160 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
23170 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
23180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23190 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
231a0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
231b0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
231c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
231d0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
231e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
231f0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
23200 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
23210 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
23220 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
23230 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
23240 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
23250 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
23260 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
23270 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
23280 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
23290 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
232a0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
232b0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
232c0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
232d0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
232e0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
232f0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
23300 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
23310 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
23320 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
23330 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
23340 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
23350 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
23360 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
23370 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
23380 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
23390 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
233a0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
233b0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
233c0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
233d0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
233e0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
233f0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
23400 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
23410 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
23420 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
23430 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
23440 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
23450 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
23460 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
23470 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
23480 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
23490 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
234a0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
234b0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
234c0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
234d0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
234e0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
234f0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
23500 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
23510 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
23520 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
23530 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
23540 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
23550 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
23560 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
23570 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
23580 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
23590 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
235a0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
235b0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
235c0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
235d0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
235e0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
235f0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
23600 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
23610 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
23620 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
23630 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
23640 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
23650 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
23660 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
23670 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
23680 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
23690 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
236a0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
236b0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
236c0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
236d0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
236e0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
236f0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
23700 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
23710 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
23720 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
23730 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
23740 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
23750 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
23760 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
23770 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
23780 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
23790 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
237a0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
237b0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
237c0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
237d0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
237e0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
237f0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
23800 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
23810 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
23820 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
23830 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
23840 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
23850 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
23860 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
23870 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
23880 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
23890 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  PI int sqlite3_l
238a0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
238b0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
238c0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
238d0 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
238e0 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
238f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
23900 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
23910 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
23920 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
23930 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
23940 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
23950 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
23960 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
23970 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
23980 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
23990 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
239a0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
239b0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
239c0 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
239d0 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
239e0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
239f0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
23a00 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
23a10 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
23a20 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
23a30 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
23a40 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
23a50 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
23a60 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
23a70 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
23a80 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
23a90 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
23aa0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
23ab0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
23ac0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
23ad0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
23ae0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
23af0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
23b00 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
23b10 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
23b20 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
23b30 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
23b40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
23b50 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
23b60 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
23b70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23b80 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
23b90 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
23ba0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
23bb0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
23bc0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
23bd0 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
23be0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
23bf0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
23c00 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
23c10 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
23c20 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
23c30 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
23c40 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
23c50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
23c60 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
23c70 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
23c80 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
23c90 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
23ca0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
23cb0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
23cc0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
23cd0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
23ce0 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
23cf0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
23d00 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
23d10 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
23d20 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
23d30 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
23d40 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
23d50 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
23d60 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
23d70 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
23d80 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
23d90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23da0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
23db0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
23dc0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
23dd0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
23de0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
23df0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
23e00 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
23e10 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
23e20 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
23e30 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
23e40 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
23e50 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
23e60 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
23e70 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23e80 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
23e90 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
23ea0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
23eb0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
23ec0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23ed0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
23ee0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
23ef0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
23f00 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
23f10 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
23f20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
23f30 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
23f40 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
23f50 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
23f60 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
23f70 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
23f80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23f90 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
23fa0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
23fb0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
23fc0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
23fd0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
23fe0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
23ff0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
24000 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
24010 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
24020 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
24030 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24040 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
24050 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
24060 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24070 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
24080 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
24090 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
240a0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
240b0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
240c0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
240d0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
240e0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
240f0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
24100 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
24110 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
24120 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24130 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
24140 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
24150 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
24160 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
24170 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
24180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24190 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
241a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
241b0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
241c0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
241d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
241e0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
241f0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
24200 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
24210 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
24220 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
24230 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
24240 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
24250 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
24260 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
24270 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
24280 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
24290 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
242a0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
242b0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
242c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
242d0 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
242e0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
242f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24300 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
24310 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
24320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24330 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
24340 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
24350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24360 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
24370 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
24380 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24390 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
243a0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
243b0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
243c0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
243d0 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
243e0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
243f0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
24400 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
24410 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
24420 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
24430 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
24440 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
24450 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
24460 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
24470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
24480 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
24490 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
244a0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
244b0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
244c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
244d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
244e0 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
244f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24500 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
24510 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
24520 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
24530 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
24540 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
24550 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
24560 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
24570 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
24580 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
24590 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
245a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
245b0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
245c0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
245d0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
245e0 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
245f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
24600 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
24610 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
24620 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
24630 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
24640 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
24650 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
24660 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
24670 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
24680 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
24690 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
246a0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
246b0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
246c0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
246d0 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
246e0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
246f0 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
24700 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
24710 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
24720 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
24730 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
24740 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
24750 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
24760 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
24770 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
24780 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
24790 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
247a0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
247b0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
247c0 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
247d0 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
247e0 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
247f0 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
24800 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
24810 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
24820 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
24830 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
24840 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
24850 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
24860 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
24870 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
24880 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
24890 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
248a0 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
248b0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
248c0 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
248d0 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
248e0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
248f0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
24900 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
24910 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
24920 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
24930 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
24940 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
24950 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
24960 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
24970 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
24980 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
24990 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
249a0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
249b0 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
249c0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
249d0 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
249e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
249f0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
24a00 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
24a10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
24a20 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
24a30 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
24a40 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
24a50 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
24a60 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
24a70 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
24a80 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
24a90 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
24aa0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
24ab0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
24ac0 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
24ad0 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
24ae0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
24af0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
24b00 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
24b10 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
24b20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24b30 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
24b40 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
24b50 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
24b60 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
24b70 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
24b80 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
24b90 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
24ba0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
24bb0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
24bc0 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
24bd0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
24be0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
24bf0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
24c00 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
24c10 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
24c20 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
24c30 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
24c40 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
24c50 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
24c60 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
24c70 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
24c80 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
24c90 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
24ca0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
24cb0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
24cc0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
24cd0 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
24ce0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
24cf0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
24d00 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
24d10 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
24d20 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
24d30 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
24d40 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
24d50 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
24d60 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
24d70 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
24d80 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
24d90 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
24da0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
24db0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
24dc0 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
24dd0 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
24de0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
24df0 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
24e00 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
24e10 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
24e20 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
24e30 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
24e40 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
24e50 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
24e60 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
24e70 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
24e80 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
24e90 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
24ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24eb0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
24ec0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
24ed0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
24ee0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
24ef0 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
24f00 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
24f10 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
24f20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24f30 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
24f40 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
24f50 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
24f60 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
24f70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
24f80 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
24f90 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
24fa0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
24fb0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
24fc0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
24fd0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
24fe0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
24ff0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
25000 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
25010 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
25020 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
25030 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
25040 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
25050 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
25060 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
25070 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
25080 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
25090 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
250a0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
250b0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
250c0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
250d0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
250e0 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
250f0 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
25100 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
25110 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
25120 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
25130 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
25140 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
25150 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
25160 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
25170 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
25180 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
25190 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
251a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
251b0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
251c0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
251d0 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
251e0 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
251f0 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
25200 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
25210 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
25220 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
25230 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
25240 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
25250 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
25260 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
25270 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
25280 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
25290 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
252a0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
252b0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
252c0 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
252d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
252e0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
252f0 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a   the .** </li>.*
25300 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54  * </ol>.*/.SQLIT
25310 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
25320 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
25330 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
25340 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
25350 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25360 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
25370 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
25380 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
25390 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
253a0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
253b0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
253c0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
253d0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
253e0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
253f0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
25400 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
25410 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
25420 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
25430 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
25440 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
25450 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
25460 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
25470 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
25480 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
25490 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
254a0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
254b0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
254c0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
254d0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
254e0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
254f0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
25500 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
25510 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
25520 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
25530 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
25540 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
25550 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
25560 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
25570 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
25580 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
25590 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
255a0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
255b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
255c0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
255d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
255e0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
255f0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
25600 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
25610 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
25620 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
25630 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
25640 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
25650 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
25660 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
25670 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
25680 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
25690 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
256a0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
256b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
256c0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
256d0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
256e0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
256f0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
25700 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
25710 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
25720 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
25730 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
25740 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
25750 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
25760 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
25770 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
25780 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
25790 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
257a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
257b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
257c0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
257d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
257e0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
257f0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
25800 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
25810 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
25820 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
25830 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
25840 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
25850 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25860 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
25870 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
25880 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
25890 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
258a0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
258b0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
258c0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
258d0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
258e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
258f0 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
25900 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
25910 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
25920 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
25930 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
25940 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25950 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  6_v2()]..*/.SQLI
25960 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
25970 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
25980 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
25990 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
259a0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
259b0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
259c0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
259d0 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
259e0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
259f0 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
25a00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
25a10 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
25a20 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
25a30 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25a40 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
25a50 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
25a60 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
25a70 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
25a80 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
25a90 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
25aa0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25ab0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
25ac0 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
25ad0 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
25ae0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
25af0 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
25b00 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
25b10 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
25b20 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
25b30 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
25b40 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
25b50 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
25b60 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
25b70 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
25b80 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
25b90 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
25ba0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
25bb0 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
25bc0 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
25bd0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
25be0 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
25bf0 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
25c00 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
25c10 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
25c20 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
25c30 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
25c40 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
25c50 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
25c60 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
25c70 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
25c80 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
25c90 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
25ca0 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
25cb0 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
25cc0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
25cd0 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
25ce0 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
25cf0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
25d00 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
25d10 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
25d20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
25d30 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
25d40 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
25d50 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
25d60 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
25d70 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
25d80 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
25d90 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
25da0 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
25db0 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
25dc0 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
25dd0 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
25de0 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
25df0 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
25e00 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
25e10 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
25e20 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
25e30 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
25e40 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
25e50 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
25e60 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
25e70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
25e80 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
25e90 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
25ea0 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
25eb0 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
25ec0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
25ed0 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
25ee0 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
25ef0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d   int sqlite3_stm
25f00 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
25f10 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
25f20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25f30 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
25f40 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25f50 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
25f60 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
25f70 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
25f80 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
25f90 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
25fa0 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
25fb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25fc0 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
25fd0 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
25fe0 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
25ff0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26000 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e   but has not run
26010 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
26020 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a  nd/or has not .*
26030 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
26040 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
26050 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
26060 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
26070 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
26080 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
26090 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
260a0 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
260b0 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
260c0 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
260d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
260e0 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
260f0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
26100 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
26110 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
26120 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
26130 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
26140 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
26150 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
26160 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
26170 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
26180 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
26190 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
261a0 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
261b0 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
261c0 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
261d0 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
261e0 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
261f0 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
26200 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
26210 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
26220 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
26230 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
26240 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
26250 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
26260 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
26270 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49  on open..*/.SQLI
26280 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26290 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
262a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
262b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
262c0 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
262d0 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
262e0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
262f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26300 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
26310 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
26320 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
26330 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
26340 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
26350 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
26360 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
26370 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
26380 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
26390 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
263a0 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
263b0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
263c0 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
263d0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
263e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
263f0 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
26400 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
26410 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
26420 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
26430 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
26440 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
26450 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
26460 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
26470 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
26480 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
26490 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
264a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
264b0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
264c0 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
264d0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
264e0 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
264f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26500 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
26510 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
26520 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
26530 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
26540 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
26550 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
26560 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
26570 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26580 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
26590 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
265a0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
265b0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
265c0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
265d0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
265e0 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
265f0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
26600 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
26610 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
26620 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
26630 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
26640 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
26650 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
26660 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
26670 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
26680 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
26690 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
266a0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
266b0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
266c0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
266d0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
266e0 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
266f0 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
26700 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
26710 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
26720 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
26730 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
26740 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
26750 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
26760 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
26770 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
26780 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
26790 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
267a0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
267b0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
267c0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
267d0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
267e0 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
267f0 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
26800 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
26810 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
26820 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
26830 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
26840 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
26850 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
26860 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26870 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
26880 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
26890 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
268a0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
268b0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
268c0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
268d0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
268e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
268f0 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
26900 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
26910 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
26920 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
26930 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26940 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
26950 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
26960 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
26970 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
26980 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
26990 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
269a0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
269b0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
269c0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
269d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
269e0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
269f0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
26a00 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
26a10 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
26a20 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
26a30 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
26a40 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
26a50 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26a60 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
26a70 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
26a80 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
26a90 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
26aa0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
26ab0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
26ac0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
26ad0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
26ae0 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
26af0 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
26b00 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
26b10 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
26b20 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
26b30 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
26b40 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
26b50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
26b60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26b70 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
26b80 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
26b90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
26ba0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
26bb0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
26bc0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
26bd0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
26be0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
26bf0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
26c00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
26c10 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
26c20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
26c30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
26c40 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
26c50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
26c60 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
26c70 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
26c80 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
26c90 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
26ca0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
26cb0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
26cc0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
26cd0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
26ce0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
26cf0 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
26d00 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
26d10 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
26d20 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
26d30 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
26d40 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
26d50 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
26d60 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
26d70 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
26d80 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
26d90 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
26da0 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
26db0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
26dc0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
26dd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
26de0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
26df0 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
26e00 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
26e10 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
26e20 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
26e30 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
26e40 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
26e50 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
26e60 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
26e70 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
26e80 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
26e90 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
26ea0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
26eb0 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
26ec0 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
26ed0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
26ee0 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
26ef0 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
26f00 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
26f10 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
26f20 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
26f30 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
26f40 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
26f50 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
26f60 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
26f70 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
26f80 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
26f90 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
26fa0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
26fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
26fc0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
26fd0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
26fe0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
26ff0 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
27000 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
27010 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
27020 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
27030 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
27040 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
27050 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
27060 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
27070 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
27080 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
27090 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
270a0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
270b0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
270c0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
270d0 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
270e0 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
270f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
27100 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
27110 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
27120 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
27130 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
27140 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
27150 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
27160 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
27170 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
27180 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
27190 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
271a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
271b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
271c0 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
271d0 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
271e0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
271f0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
27200 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
27210 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
27220 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
27230 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
27240 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
27250 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
27260 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
27270 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
27280 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
27290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
272a0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
272b0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
272c0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
272d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
272e0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
272f0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
27300 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
27310 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
27320 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
27330 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
27340 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
27350 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
27360 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
27370 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
27380 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
27390 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
273a0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
273b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
273c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
273d0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
273e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
273f0 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
27400 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
27410 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
27420 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
27430 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
27440 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
27450 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
27460 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
27470 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
27480 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
27490 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
274a0 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
274b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
274c0 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
274d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
274e0 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
274f0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
27500 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
27510 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
27520 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61  ) then that para
27530 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
27540 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
27550 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
27560 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
27570 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
27580 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
27590 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
275a0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
275b0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
275c0 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
275d0 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
275e0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
275f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
27600 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
27610 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
27620 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
27630 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
27640 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
27650 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
27660 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
27670 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
27680 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
27690 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
276a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
276b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
276c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
276d0 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
276e0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
276f0 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
27700 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
27710 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
27720 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
27730 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
27740 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
27750 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
27760 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
27770 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
27780 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
27790 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
277a0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
277b0 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  lob(),.** sqlite
277c0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f  3_bind_text(), o
277d0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
277e0 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20  ext16() fails.  
277f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
27800 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
27810 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
27820 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
27830 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
27840 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
27850 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
27860 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
27870 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
27880 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
27890 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
278a0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
278b0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
278c0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
278d0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
278e0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
278f0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
27900 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
27910 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
27920 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
27930 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
27940 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
27950 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
27960 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
27970 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
27980 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
27990 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
279a0 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
279b0 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
279c0 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
279d0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
279e0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
279f0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
27a00 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
27a10 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
27a20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
27a30 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
27a40 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
27a50 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
27a60 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
27a70 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
27a80 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
27a90 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
27aa0 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
27ab0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
27ac0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
27ad0 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
27ae0 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
27af0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
27b00 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
27b10 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
27b20 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
27b30 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
27b40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
27b50 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
27b60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
27b70 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
27b80 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
27b90 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
27ba0 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
27bb0 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
27bc0 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
27bd0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
27be0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
27bf0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
27c00 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
27c10 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
27c20 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
27c30 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
27c40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27c50 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
27c60 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
27c70 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
27c80 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
27c90 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
27ca0 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
27cb0 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
27cc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27cd0 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
27ce0 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
27cf0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
27d00 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
27d10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
27d20 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
27d30 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
27d40 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
27d50 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
27d60 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
27d70 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
27d80 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
27d90 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
27da0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
27db0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
27dc0 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
27dd0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
27de0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
27df0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
27e00 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
27e10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
27e20 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
27e30 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27e40 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
27e50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27e60 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
27e70 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
27e80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27e90 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
27ea0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
27eb0 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
27ec0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
27ed0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27ee0 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
27ef0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27f00 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  int, double);.SQ
27f10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27f20 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
27f30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27f40 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
27f50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
27f60 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
27f70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
27f80 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51  lite3_int64);.SQ
27f90 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27fa0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
27fb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27fc0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
27fd0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27fe0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
27ff0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
28000 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
28010 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
28020 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28030 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
28040 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28050 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
28060 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
28070 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
28080 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
28090 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
280a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
280b0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
280c0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
280d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
280e0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
280f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
28100 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
28110 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
28120 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
28130 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
28140 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
28150 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
28160 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
28170 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
28180 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28190 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
281a0 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
281b0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
281c0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
281d0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
281e0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
281f0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
28200 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
28210 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
28220 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
28230 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
28240 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
28250 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
28260 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
28270 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
28280 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
28290 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
282a0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
282b0 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
282c0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
282d0 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
282e0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
282f0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
28300 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
28310 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
28320 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
28330 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
28340 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
28350 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
28360 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
28370 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
28380 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
28390 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
283a0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
283b0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
283c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
283d0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
283e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
283f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28400 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
28410 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
28420 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
28430 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
28440 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
28450 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28460 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
28470 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
28480 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
28490 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
284a0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
284b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
284c0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
284d0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
284e0 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
284f0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
28500 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
28510 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
28520 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
28530 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
28540 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
28550 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
28560 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
28570 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
28580 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
28590 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
285a0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
285b0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
285c0 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
285d0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
285e0 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
285f0 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
28600 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
28610 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
28620 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
28630 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
28640 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
28650 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
28660 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
28670 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
28680 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
28690 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
286a0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
286b0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
286c0 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
286d0 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
286e0 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
286f0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
28700 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
28710 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
28720 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
28730 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
28740 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
28750 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
28760 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
28770 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
28780 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28790 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
287a0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
287b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
287c0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
287d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
287e0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
287f0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
28800 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28810 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
28820 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
28830 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
28840 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
28850 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
28860 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
28870 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
28880 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
28890 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
288a0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
288b0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
288c0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
288d0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
288e0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
288f0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
28900 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
28910 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
28920 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
28930 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
28940 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
28950 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
28960 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
28970 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
28980 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
28990 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
289a0 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
289b0 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
289c0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
289d0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
289e0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
289f0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
28a00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28a10 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
28a20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
28a30 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
28a40 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
28a50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
28a60 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
28a70 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
28a80 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28a90 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
28aa0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
28ab0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28ac0 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
28ad0 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
28ae0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
28af0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28b00 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
28b10 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
28b20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
28b30 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
28b40 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
28b50 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
28b60 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
28b70 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
28b80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
28b90 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
28ba0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28bb0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
28bc0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
28bd0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
28be0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
28bf0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
28c00 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
28c10 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
28c20 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
28c30 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
28c40 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
28c50 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
28c60 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
28c70 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
28c80 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
28c90 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
28ca0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
28cb0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
28cc0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
28cd0 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
28ce0 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
28cf0 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
28d00 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
28d10 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
28d20 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
28d30 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28d40 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
28d50 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
28d60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
28d70 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
28d80 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
28d90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
28da0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
28db0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
28dc0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
28dd0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
28de0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
28df0 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
28e00 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
28e10 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
28e20 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
28e30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
28e40 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
28e50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28e60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
28e70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
28e80 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
28e90 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
28ea0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
28eb0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
28ec0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
28ed0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
28ee0 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
28ef0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
28f00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28f10 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
28f20 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
28f30 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
28f40 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
28f50 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
28f60 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
28f70 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
28f80 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
28f90 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
28fa0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
28fb0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
28fc0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
28fd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28fe0 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
28ff0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
29000 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
29010 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
29020 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
29030 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
29040 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
29050 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29060 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
29070 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
29080 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
29090 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
290a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
290b0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
290c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
290d0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
290e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
290f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
29100 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
29110 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
29120 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
29130 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
29140 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
29150 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
29160 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
29170 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
29180 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
29190 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
291a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
291b0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
291c0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
291d0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
291e0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
291f0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
29200 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
29210 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
29220 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
29230 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
29240 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
29250 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
29260 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
29270 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
29280 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
29290 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
292a0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
292b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
292c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
292d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
292e0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
292f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29300 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
29310 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
29320 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
29330 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
29340 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
29350 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
29360 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
29370 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
29380 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
29390 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
293a0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
293b0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
293c0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
293d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
293e0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
293f0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
29400 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
29410 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
29420 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
29430 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
29440 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
29450 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
29460 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
29470 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
29480 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
29490 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
294a0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
294b0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
294c0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
294d0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
294e0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
294f0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
29500 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
29510 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
29520 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
29530 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
29540 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
29550 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
29560 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
29570 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
29580 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
29590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
295a0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
295b0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
295c0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
295d0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
295e0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
295f0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
29600 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
29610 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
29620 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
29630 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
29640 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
29650 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
29660 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
29670 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
29680 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
29690 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
296a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
296b0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
296c0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
296d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
296e0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
296f0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
29700 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
29710 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
29720 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
29730 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
29740 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
29750 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
29760 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
29770 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
29780 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
29790 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
297a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
297b0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
297c0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
297d0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
297e0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
297f0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
29800 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
29810 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
29820 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
29830 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
29840 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
29850 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
29860 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
29870 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
29880 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
29890 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
298a0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
298b0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
298c0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
298d0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
298e0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
298f0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
29900 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
29910 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
29920 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
29930 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
29940 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
29950 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
29960 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
29970 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
29980 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
29990 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
299a0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
299b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
299c0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
299d0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
299e0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
299f0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
29a00 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
29a10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
29a20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
29a30 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
29a40 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
29a50 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
29a60 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
29a70 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
29a80 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
29a90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
29aa0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
29ab0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
29ac0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
29ad0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
29ae0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
29af0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
29b00 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
29b10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29b20 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
29b30 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
29b40 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
29b50 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
29b60 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
29b70 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
29b80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
29b90 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
29ba0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
29bb0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
29bc0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
29bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
29be0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
29bf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
29c00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
29c10 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
29c20 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
29c30 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
29c40 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
29c50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
29c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
29c70 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
29c80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
29c90 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
29ca0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
29cb0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
29cc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
29cd0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
29ce0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
29cf0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
29d00 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
29d10 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
29d20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
29d30 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
29d40 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
29d50 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
29d60 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
29d70 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
29d80 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
29d90 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
29da0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
29db0 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
29dc0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
29dd0 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
29de0 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
29df0 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
29e00 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
29e10 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
29e20 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
29e30 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
29e40 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
29e50 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
29e60 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
29e70 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
29e80 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
29e90 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
29ea0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
29eb0 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
29ec0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
29ed0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
29ee0 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
29ef0 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
29f00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
29f10 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
29f20 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
29f30 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
29f40 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
29f50 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
29f60 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
29f70 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
29f80 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
29f90 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
29fa0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
29fb0 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
29fc0 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
29fd0 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
29fe0 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
29ff0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
2a000 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
2a010 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
2a020 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
2a030 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
2a040 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2a050 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
2a060 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
2a070 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
2a080 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
2a090 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
2a0a0 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
2a0b0 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
2a0c0 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
2a0d0 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
2a0e0 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
2a0f0 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
2a100 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
2a110 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
2a120 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
2a130 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
2a140 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
2a150 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2a160 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
2a170 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
2a180 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
2a190 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
2a1a0 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49   values..*/.SQLI
2a1b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2a1c0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2a1d0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
2a1e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2a1f0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2a200 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2a210 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2a220 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a230 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a240 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2a250 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2a260 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2a270 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a280 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2a290 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2a2a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2a2b0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2a2c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a2d0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2a2e0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2a2f0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2a300 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2a310 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a320 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2a330 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2a340 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2a350 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2a360 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2a370 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2a380 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2a390 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2a3a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2a3b0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2a3c0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2a3d0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2a3e0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2a3f0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2a400 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2a410 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2a420 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2a430 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2a440 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2a450 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2a460 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2a470 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2a480 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2a490 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2a4a0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2a4b0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2a4c0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2a4d0 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2a4e0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2a4f0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2a500 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2a510 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2a520 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2a530 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2a540 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2a550 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2a560 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2a570 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2a580 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2a590 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2a5a0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2a5b0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2a5c0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2a5d0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2a5e0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2a5f0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2a600 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2a610 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2a620 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2a630 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2a640 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2a650 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2a660 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2a670 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2a680 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2a690 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2a6a0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2a6b0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2a6c0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2a6d0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2a6e0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2a6f0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2a700 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2a710 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2a720 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2a730 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2a740 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2a750 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2a760 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2a770 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2a780 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2a790 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2a7a0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2a7b0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2a7c0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2a7d0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2a7e0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2a7f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2a800 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2a810 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2a820 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2a830 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2a840 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2a850 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2a860 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2a870 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2a880 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2a890 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2a8a0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2a8b0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2a8c0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2a8d0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2a8e0 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2a8f0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2a900 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2a910 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2a920 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2a930 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2a940 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2a950 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2a960 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2a970 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2a980 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2a990 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2a9a0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2a9b0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2a9c0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2a9d0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2a9e0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2a9f0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2aa00 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2aa10 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2aa20 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2aa30 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2aa40 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2aa50 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2aa60 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2aa70 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2aa80 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2aa90 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2aaa0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2aab0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2aac0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2aad0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2aae0 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2aaf0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2ab00 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2ab10 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2ab20 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2ab30 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2ab40 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2ab50 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2ab60 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2ab70 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2ab80 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2ab90 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2aba0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2abb0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2abc0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2abd0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2abe0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2abf0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2ac00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2ac10 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2ac20 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2ac30 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2ac40 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2ac50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2ac60 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2ac70 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2ac80 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2ac90 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2aca0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2acb0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2acc0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2acd0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2ace0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2acf0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2ad00 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2ad10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2ad20 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2ad30 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2ad40 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2ad50 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2ad60 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2ad70 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2ad80 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2ad90 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2ada0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2adb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2adc0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2add0 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2ade0 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2adf0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2ae00 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2ae10 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2ae20 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2ae30 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2ae40 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2ae50 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2ae60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2ae70 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2ae80 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2ae90 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2aea0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2aeb0 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2aec0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2aed0 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2aee0 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2aef0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2af00 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2af10 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2af20 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2af30 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2af40 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2af50 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2af60 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2af70 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2af80 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2af90 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2afa0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2afb0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2afc0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2afd0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2afe0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2aff0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2b000 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2b010 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2b020 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2b030 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2b040 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2b050 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2b060 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2b070 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2b080 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2b090 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2b0a0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2b0b0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2b0c0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2b0d0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2b0e0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2b0f0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2b100 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2b110 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2b120 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2b130 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2b140 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2b150 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b160 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2b170 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2b180 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2b190 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2b1a0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2b1b0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2b1c0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2b1d0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2b1e0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2b1f0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2b200 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2b210 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2b220 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2b230 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2b240 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2b250 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2b260 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2b270 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2b280 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2b290 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2b2a0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2b2b0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2b2c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2b2d0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2b2e0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2b2f0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2b300 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2b310 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2b320 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2b330 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2b340 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2b350 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2b360 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2b370 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
2b380 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2b390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b3a0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
2b3b0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
2b3c0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
2b3d0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2b3e0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2b3f0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2b400 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2b410 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
2b420 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2b430 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
2b440 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2b450 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
2b460 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
2b470 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
2b480 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
2b490 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
2b4a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
2b4b0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
2b4c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
2b4d0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2b4e0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
2b4f0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
2b500 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
2b510 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2b520 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
2b530 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
2b540 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
2b550 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
2b560 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2b570 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
2b580 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
2b590 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
2b5a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2b5b0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
2b5c0 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
2b5d0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2b5e0 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
2b5f0 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
2b600 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2b610 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
2b620 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
2b630 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
2b640 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
2b650 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
2b660 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
2b670 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
2b680 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
2b690 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
2b6a0 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
2b6b0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
2b6c0 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
2b6d0 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
2b6e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2b6f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2b700 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
2b710 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
2b720 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
2b730 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2b740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b750 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
2b760 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
2b770 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2b780 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
2b790 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
2b7a0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
2b7b0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
2b7c0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
2b7d0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
2b7e0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2b7f0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
2b800 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
2b810 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
2b820 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
2b830 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
2b840 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
2b850 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2b860 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2b870 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2b880 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2b890 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2b8a0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2b8b0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2b8c0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2b8d0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2b8e0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2b8f0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2b900 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2b910 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2b920 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2b930 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2b940 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2b950 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2b960 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2b970 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2b980 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2b990 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2b9a0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2b9b0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2b9c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2b9d0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2b9e0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2b9f0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2ba00 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2ba10 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2ba20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2ba30 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2ba40 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2ba50 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2ba60 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
2ba70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
2ba80 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2ba90 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2baa0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
2bab0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
2bac0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
2bad0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2bae0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2baf0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2bb00 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2bb10 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2bb20 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2bb30 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2bb40 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2bb50 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2bb60 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2bb70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bb80 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2bb90 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2bba0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2bbb0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2bbc0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2bbd0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2bbe0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2bbf0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2bc00 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2bc10 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2bc20 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2bc30 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2bc40 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2bc50 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2bc60 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2bc70 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2bc80 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2bc90 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2bca0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2bcb0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2bcc0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2bcd0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2bce0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2bcf0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2bd00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2bd10 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2bd20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2bd30 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2bd40 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2bd50 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2bd60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2bd70 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2bd80 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2bd90 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2bda0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2bdb0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2bdc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2bdd0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2bde0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2bdf0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2be00 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2be10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2be20 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2be30 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2be40 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2be50 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2be60 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2be70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2be80 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2be90 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2bea0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2beb0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2bec0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2bed0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2bee0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2bef0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2bf00 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2bf10 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2bf20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2bf30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2bf40 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2bf50 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2bf60 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2bf70 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2bf80 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2bf90 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2bfa0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2bfb0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2bfc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2bfd0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
2bfe0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
2bff0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2c000 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
2c010 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
2c020 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
2c030 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
2c040 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
2c050 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
2c060 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2c070 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
2c080 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2c090 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
2c0a0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
2c0b0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
2c0c0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
2c0d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2c0e0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
2c0f0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
2c100 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
2c110 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
2c120 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
2c130 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
2c140 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2c150 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
2c160 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2c170 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2c180 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
2c190 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
2c1a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
2c1b0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
2c1c0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2c1d0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
2c1e0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
2c1f0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
2c200 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2c210 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2c220 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
2c230 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2c240 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2c250 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2c260 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2c270 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2c280 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2c290 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2c2a0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2c2b0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2c2c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2c2d0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2c2e0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2c2f0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2c300 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2c310 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2c320 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2c330 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2c340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c350 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
2c360 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2c370 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2c380 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2c390 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
2c3a0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2c3b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2c3c0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2c3d0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2c3e0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2c3f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c400 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
2c410 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
2c420 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2c430 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
2c440 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2c450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c460 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
2c470 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2c480 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c490 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2c4a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2c4b0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2c4c0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
2c4d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c4e0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
2c4f0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2c500 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
2c510 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2c520 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2c530 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2c540 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2c550 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2c560 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c570 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2c580 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2c590 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2c5a0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
2c5b0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2c5c0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2c5d0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2c5e0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2c5f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2c600 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2c610 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c620 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
2c630 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
2c640 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
2c650 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c660 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
2c670 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c680 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
2c690 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
2c6a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
2c6b0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2c6c0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
2c6d0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
2c6e0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2c6f0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2c700 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2c710 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
2c720 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
2c730 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
2c740 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
2c750 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
2c760 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2c770 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
2c780 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
2c790 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c7a0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
2c7b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2c7c0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
2c7d0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
2c7e0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
2c7f0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
2c800 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2c810 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2c820 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2c830 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2c840 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c850 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
2c860 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
2c870 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c880 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
2c890 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2c8a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c8b0 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
2c8c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c8d0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
2c8e0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2c8f0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
2c900 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2c910 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2c920 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2c930 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2c940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c950 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2c960 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2c970 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2c980 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2c990 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2c9a0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2c9b0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2c9c0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2c9d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2c9e0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2c9f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ca00 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
2ca10 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2ca20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2ca30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2ca40 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2ca50 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2ca60 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2ca70 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2ca80 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2ca90 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2caa0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2cab0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2cac0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2cad0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2cae0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2caf0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2cb00 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2cb10 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2cb20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2cb30 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2cb40 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2cb50 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2cb60 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2cb70 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2cb80 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2cb90 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2cba0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2cbb0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2cbc0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2cbd0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2cbe0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2cbf0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2cc00 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2cc10 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2cc20 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2cc30 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2cc40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2cc50 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2cc60 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2cc70 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2cc80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2cc90 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2cca0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2ccb0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2ccc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2ccd0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2cce0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2ccf0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2cd00 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2cd10 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2cd20 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2cd30 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2cd40 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2cd50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2cd60 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2cd70 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2cd80 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2cd90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2cda0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2cdb0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2cdc0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
2cdd0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2cde0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2cdf0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2ce00 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2ce10 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
2ce20 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2ce30 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2ce40 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
2ce50 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
2ce60 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2ce70 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2ce80 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
2ce90 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2cea0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2ceb0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
2cec0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2ced0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
2cee0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
2cef0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
2cf00 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
2cf10 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
2cf20 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
2cf30 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
2cf40 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2cf50 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2cf60 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2cf70 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2cf80 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
2cf90 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2cfa0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2cfb0 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
2cfc0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
2cfd0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2cfe0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
2cff0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
2d000 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
2d010 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
2d020 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
2d030 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
2d040 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
2d050 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
2d060 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
2d070 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
2d080 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
2d090 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
2d0a0 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
2d0b0 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
2d0c0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
2d0d0 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
2d0e0 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
2d0f0 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
2d100 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
2d110 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
2d120 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2d130 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
2d140 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
2d150 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2d160 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
2d170 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2d180 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
2d190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d1a0 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
2d1b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d1c0 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
2d1d0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
2d1e0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
2d1f0 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
2d200 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
2d210 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
2d220 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
2d230 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2d240 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2d250 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
2d260 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2d270 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
2d280 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2d290 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2d2a0 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
2d2b0 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
2d2c0 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
2d2d0 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
2d2e0 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
2d2f0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2d300 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2d310 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
2d320 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d330 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
2d340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d350 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2d360 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2d370 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2d380 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2d390 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
2d3a0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2d3b0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
2d3c0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2d3d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2d3e0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2d3f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2d400 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2d410 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2d420 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2d430 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
2d440 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2d450 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
2d460 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
2d470 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
2d480 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
2d490 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
2d4a0 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
2d4b0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
2d4c0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
2d4d0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2d4e0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
2d4f0 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
2d500 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
2d510 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
2d520 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
2d530 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
2d540 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
2d550 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
2d560 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
2d570 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
2d580 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
2d590 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
2d5a0 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
2d5b0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
2d5c0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
2d5d0 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
2d5e0 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
2d5f0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
2d600 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
2d610 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
2d620 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
2d630 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
2d640 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2d650 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
2d660 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2d670 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2d680 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2d690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2d6a0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2d6b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d6c0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2d6d0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2d6e0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
2d6f0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2d700 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
2d710 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
2d720 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2d730 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
2d740 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
2d750 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
2d760 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2d770 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
2d780 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2d790 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
2d7a0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
2d7b0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
2d7c0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
2d7d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2d7e0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
2d7f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d800 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
2d810 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
2d820 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
2d830 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
2d840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d850 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2d860 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
2d870 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
2d880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d890 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
2d8a0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
2d8b0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2d8c0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
2d8d0 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
2d8e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2d8f0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
2d900 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2d910 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
2d920 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2d930 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
2d940 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
2d950 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
2d960 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2d970 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2d980 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2d990 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
2d9a0 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
2d9b0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
2d9c0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
2d9d0 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
2d9e0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
2d9f0 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
2da00 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
2da10 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
2da20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2da30 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2da40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2da50 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2da60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2da70 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2da80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2da90 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2daa0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2dab0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2dac0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2dad0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2dae0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2daf0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2db00 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2db10 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2db20 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2db30 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2db40 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2db50 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2db60 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2db70 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2db80 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2db90 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c  NOMEM].)^.*/.SQL
2dba0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2dbb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2dbc0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2dbd0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2dbe0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2dbf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2dc00 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2dc10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2dc20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2dc30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2dc40 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
2dc50 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2dc60 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
2dc70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2dc80 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2dc90 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2dca0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2dcb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2dcc0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2dcd0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2dce0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2dcf0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
2dd00 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
2dd10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2dd20 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2dd30 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20   const unsigned 
2dd40 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2dd50 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2dd60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2dd70 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
2dd80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2dd90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2dda0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ddb0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2ddc0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ddd0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
2dde0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ddf0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2de00 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  PI sqlite3_value
2de10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2de20 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2de30 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2de40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2de50 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2de60 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2de70 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2de80 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2de90 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2dea0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2deb0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2dec0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2ded0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2dee0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2def0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2df00 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2df10 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2df20 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2df30 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2df40 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2df50 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2df60 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2df70 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2df80 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2df90 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2dfa0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2dfb0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2dfc0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2dfd0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2dfe0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2dff0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2e000 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2e010 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e020 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2e030 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2e040 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2e050 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2e060 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2e070 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2e080 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2e090 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2e0a0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2e0b0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2e0c0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2e0d0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2e0e0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2e0f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2e100 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2e110 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2e120 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2e130 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2e140 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2e150 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2e160 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2e170 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2e180 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2e190 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2e1a0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2e1b0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2e1c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2e1d0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2e1e0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2e1f0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2e200 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2e210 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2e220 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2e230 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2e240 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2e250 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2e260 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2e270 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2e280 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2e290 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2e2a0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2e2b0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2e2c0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2e2d0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2e2e0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2e2f0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2e300 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2e310 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e320 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2e330 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2e340 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2e350 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2e360 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2e370 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2e380 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2e390 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2e3a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e3b0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2e3c0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2e3d0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2e3e0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2e3f0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
2e400 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
2e410 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
2e420 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
2e430 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
2e440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e450 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2e460 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
2e470 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
2e480 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
2e490 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
2e4a0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
2e4b0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
2e4c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2e4d0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2e4e0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2e4f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e500 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
2e510 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2e520 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2e530 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2e540 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2e550 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2e560 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2e570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2e580 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2e590 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2e5a0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
2e5b0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2e5c0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
2e5d0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
2e5e0 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
2e5f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2e600 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2e610 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
2e620 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2e630 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2e640 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2e650 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2e660 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
2e670 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
2e680 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
2e690 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2e6a0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
2e6b0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
2e6c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2e6d0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2e6e0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
2e6f0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
2e700 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
2e710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e720 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2e730 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2e740 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c  ement] S..*/.SQL
2e750 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e760 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2e770 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2e780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e790 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2e7a0 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2e7b0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2e7c0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2e7d0 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
2e7e0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2e7f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2e800 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
2e810 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2e820 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2e830 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
2e840 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2e850 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
2e860 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
2e870 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2e880 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
2e890 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
2e8a0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2e8b0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
2e8c0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
2e8d0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
2e8e0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
2e8f0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
2e900 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
2e910 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
2e920 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2e930 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
2e940 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
2e950 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
2e960 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2e970 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
2e980 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
2e990 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
2e9a0 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
2e9b0 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
2e9c0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
2e9d0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2e9e0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2e9f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2ea00 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2ea10 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2ea20 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
2ea30 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
2ea40 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
2ea50 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
2ea60 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
2ea70 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
2ea80 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2ea90 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
2eaa0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2eab0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
2eac0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
2ead0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
2eae0 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
2eaf0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2eb00 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2eb10 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2eb20 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2eb30 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
2eb40 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
2eb50 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
2eb60 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
2eb70 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
2eb80 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
2eb90 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
2eba0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2ebb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
2ebc0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
2ebd0 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
2ebe0 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
2ebf0 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
2ec00 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
2ec10 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
2ec20 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
2ec30 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
2ec40 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
2ec50 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
2ec60 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
2ec70 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
2ec80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2ec90 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2eca0 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
2ecb0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2ecc0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
2ecd0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2ece0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
2ecf0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
2ed00 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
2ed10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ed20 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2ed30 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
2ed40 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2ed50 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
2ed60 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
2ed70 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
2ed80 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2ed90 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
2eda0 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
2edb0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
2edc0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
2edd0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
2ede0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
2edf0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
2ee00 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2ee10 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ee20 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
2ee30 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
2ee40 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
2ee50 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
2ee60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
2ee70 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
2ee80 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76   parameters.  Ev
2ee90 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ery SQL function
2eea0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2eeb0 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20  must be able to 
2eec0 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46  work.** with UTF
2eed0 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
2eee0 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
2eef0 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
2ef00 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
2ef10 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
2ef20 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
2ef30 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
2ef40 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
2ef50 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
2ef60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ef70 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
2ef80 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ef90 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
2efa0 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
2efb0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
2efc0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
2efd0 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
2efe0 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
2eff0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2f000 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2f010 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
2f020 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
2f030 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
2f040 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
2f050 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
2f060 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
2f070 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
2f080 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
2f090 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
2f0a0 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
2f0b0 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
2f0c0 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
2f0d0 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
2f0e0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
2f0f0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
2f100 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
2f110 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
2f120 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
2f130 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
2f140 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2f150 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
2f160 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
2f170 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
2f180 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
2f190 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2f1a0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
2f1b0 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
2f1c0 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
2f1d0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
2f1e0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
2f1f0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
2f200 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
2f210 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
2f220 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2f230 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2f240 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
2f250 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
2f260 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2f270 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2f280 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
2f290 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
2f2a0 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
2f2b0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
2f2c0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
2f2d0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
2f2e0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
2f2f0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2f300 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2f310 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
2f320 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
2f330 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
2f340 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
2f350 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
2f360 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
2f370 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
2f380 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
2f390 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
2f3a0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
2f3b0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
2f3c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
2f3d0 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
2f3e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
2f3f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2f400 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
2f410 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
2f420 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
2f430 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2f440 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
2f450 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2f460 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
2f470 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
2f480 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
2f490 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
2f4a0 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
2f4b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f4c0 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
2f4d0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2f4e0 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
2f4f0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
2f500 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
2f510 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
2f520 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
2f530 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
2f540 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
2f550 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
2f560 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
2f570 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
2f580 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
2f590 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
2f5a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2f5b0 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
2f5c0 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
2f5d0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
2f5e0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2f5f0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
2f600 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
2f610 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
2f620 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
2f630 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2f640 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
2f650 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
2f660 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
2f670 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
2f680 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
2f690 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
2f6a0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
2f6b0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
2f6c0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
2f6d0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
2f6e0 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
2f6f0 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
2f700 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
2f710 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
2f720 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
2f730 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
2f740 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2f750 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
2f760 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
2f770 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
2f780 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2f790 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2f7a0 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
2f7b0 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
2f7c0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2f7d0 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
2f7e0 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
2f7f0 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
2f800 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
2f810 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
2f820 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2f830 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2f840 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2f850 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
2f860 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2f870 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
2f880 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
2f890 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
2f8a0 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
2f8b0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2f8c0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2f8d0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2f8e0 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
2f8f0 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
2f900 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
2f910 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
2f920 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
2f930 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2f940 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2f950 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
2f960 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f970 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
2f980 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
2f990 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
2f9a0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
2f9b0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
2f9c0 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
2f9d0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
2f9e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
2f9f0 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
2fa00 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
2fa10 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
2fa20 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
2fa30 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2fa40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2fa50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fa60 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
2fa70 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2fa80 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2fa90 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2faa0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2fab0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2fac0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2fad0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2fae0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2faf0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2fb00 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2fb10 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2fb20 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2fb30 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2fb40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2fb50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2fb60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fb70 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
2fb80 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2fb90 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
2fba0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2fbb0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2fbc0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2fbd0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2fbe0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2fbf0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2fc00 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2fc10 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2fc20 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2fc30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2fc40 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2fc50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fc60 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
2fc70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2fc80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2fc90 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2fca0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2fcb0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2fcc0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2fcd0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2fce0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2fcf0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2fd00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2fd10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2fd20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2fd30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2fd40 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2fd50 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2fd60 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2fd70 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
2fd80 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
2fd90 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
2fda0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
2fdb0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
2fdc0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
2fdd0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
2fde0 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
2fdf0 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
2fe00 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
2fe10 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
2fe20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2fe30 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
2fe40 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2fe50 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
2fe60 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2fe70 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
2fe80 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2fe90 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
2fea0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
2feb0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2fec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2fed0 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
2fee0 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
2fef0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ff00 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
2ff10 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
2ff20 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
2ff30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2ff40 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
2ff50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ff60 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
2ff70 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
2ff80 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
2ff90 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
2ffa0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
2ffb0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
2ffc0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
2ffd0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
2ffe0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
2fff0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
30000 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
30010 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
30020 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
30030 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
30040 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
30050 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
30060 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
30070 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
30080 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
30090 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
300a0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
300b0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
300c0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
300d0 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
300e0 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
300f0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
30100 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
30110 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30120 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
30130 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
30140 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
30150 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
30160 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
30170 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
30180 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
30190 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
301a0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
301b0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
301c0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
301d0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
301e0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
301f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
30200 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
30210 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
30220 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
30230 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
30240 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
30250 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
30260 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
30270 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
30280 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
30290 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
302a0 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
302b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
302c0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
302d0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
302e0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
302f0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
30300 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
30310 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
30320 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
30330 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
30340 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
30350 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
30360 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
30370 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
30380 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
30390 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
303a0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
303b0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
303c0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
303d0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
303e0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
303f0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
30400 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30410 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
30420 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30430 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
30440 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
30450 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
30460 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
30470 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
30480 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
30490 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
304a0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
304b0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
304c0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
304d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
304e0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
304f0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
30500 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
30510 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
30520 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
30530 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
30540 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
30550 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
30560 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
30570 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
30580 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
30590 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
305a0 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
305b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
305c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
305d0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
305e0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
305f0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
30600 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30610 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
30620 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
30630 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
30640 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
30650 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
30660 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
30670 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
30680 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
30690 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
306a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
306b0 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
306c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
306d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
306e0 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
306f0 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
30700 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
30710 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
30720 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
30730 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30740 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
30750 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
30760 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
30770 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
30780 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
30790 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
307a0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
307b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
307c0 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
307d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
307e0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
307f0 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
30800 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
30810 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
30820 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
30830 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
30840 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
30850 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
30860 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
30870 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
30880 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
30890 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
308a0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
308b0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
308c0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
308d0 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
308e0 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
308f0 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
30900 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
30910 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
30920 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
30930 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
30940 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
30950 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
30960 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
30970 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
30980 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
30990 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
309a0 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
309b0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
309c0 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
309d0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
309e0 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
309f0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
30a00 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
30a10 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
30a20 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
30a30 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
30a40 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
30a50 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
30a60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
30a70 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
30a80 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
30a90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
30aa0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
30ab0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
30ac0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
30ad0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
30ae0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
30af0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
30b00 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
30b10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30b20 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
30b30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30b40 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
30b50 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
30b60 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
30b70 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
30b80 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
30b90 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
30ba0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
30bb0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
30bc0 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ters..*/.SQLITE_
30bd0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
30be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
30bf0 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
30c00 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
30c10 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
30c20 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
30c30 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
30c40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
30c50 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
30c60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
30c70 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20  LITE_API double 
30c80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
30c90 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
30ca0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
30cb0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
30cc0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
30cd0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
30ce0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
30cf0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
30d00 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
30d10 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
30d20 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20   const unsigned 
30d30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
30d40 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
30d50 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
30d60 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
30d70 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
30d80 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
30d90 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
30da0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
30db0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30dc0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
30dd0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
30de0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
30df0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30e00 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
30e10 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
30e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
30e30 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
30e40 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
30e50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
30e60 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
30e70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
30e80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30e90 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
30ea0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
30eb0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
30ec0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
30ed0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
30ee0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
30ef0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
30f00 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
30f10 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
30f20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
30f30 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
30f40 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30f50 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
30f60 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
30f70 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
30f80 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
30f90 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
30fa0 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
30fb0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
30fc0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
30fd0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
30fe0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
30ff0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
31000 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
31010 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
31020 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
31030 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31040 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
31050 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31060 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
31070 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
31080 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
31090 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
310a0 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
310b0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
310c0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
310d0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
310e0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
310f0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
31100 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
31110 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
31120 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
31130 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
31140 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
31150 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
31160 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
31170 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
31180 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
31190 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
311a0 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
311b0 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
311c0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
311d0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
311e0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
311f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
31200 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
31210 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
31220 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
31230 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
31240 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31250 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31260 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
31270 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
31280 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
31290 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
312a0 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
312b0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
312c0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
312d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
312e0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
312f0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
31300 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31310 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
31320 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
31330 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
31340 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
31350 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
31360 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
31370 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
31380 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
31390 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
313a0 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
313b0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
313c0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
313d0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
313e0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
313f0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
31400 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
31410 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
31420 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
31430 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
31440 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31450 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
31460 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
31470 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
31480 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
31490 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
314a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
314b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
314c0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
314d0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
314e0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
314f0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
31500 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
31510 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
31520 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
31530 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
31540 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
31550 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
31560 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
31570 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
31580 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
31590 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
315a0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
315b0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
315c0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
315d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
315e0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
315f0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
31600 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
31610 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
31620 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
31630 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31640 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
31650 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
31660 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
31670 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
31680 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
31690 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
316a0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
316b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
316c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
316d0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
316e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
316f0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
31700 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
31710 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
31720 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
31730 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
31740 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
31750 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
31760 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31770 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
31780 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31790 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
317a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
317b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
317c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
317d0 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
317e0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
317f0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
31800 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
31810 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
31820 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
31830 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
31840 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
31850 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
31860 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
31870 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
31880 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
31890 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
318a0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
318b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
318c0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
318d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
318e0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
318f0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
31900 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
31910 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31920 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
31930 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
31940 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65   sqlite3 *sqlite
31950 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
31960 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
31970 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
31980 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
31990 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
319a0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
319b0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
319c0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
319d0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
319e0 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
319f0 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
31a00 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
31a10 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
31a20 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
31a30 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
31a40 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
31a50 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
31a60 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
31a70 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
31a80 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
31a90 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
31aa0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
31ab0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
31ac0 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
31ad0 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
31ae0 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
31af0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
31b00 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
31b10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
31b20 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
31b30 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
31b40 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
31b50 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
31b60 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
31b70 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
31b80 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
31b90 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
31ba0 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
31bb0 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
31bc0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
31bd0 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
31be0 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
31bf0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
31c00 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
31c10 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
31c20 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
31c30 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
31c40 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
31c50 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
31c60 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
31c70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
31c80 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
31c90 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
31ca0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
31cb0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
31cc0 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
31cd0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
31ce0 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
31cf0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
31d00 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
31d10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31d20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
31d30 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
31d40 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
31d50 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
31d60 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
31d70 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
31d80 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
31d90 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
31da0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
31db0 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
31dc0 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
31dd0 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
31de0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
31df0 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
31e00 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
31e10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
31e20 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
31e30 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
31e40 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
31e50 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
31e60 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
31e70 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
31e80 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
31e90 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
31ea0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31eb0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
31ec0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
31ed0 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
31ee0 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
31ef0 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
31f00 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
31f10 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
31f20 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
31f30 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
31f40 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
31f50 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
31f60 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
31f70 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
31f80 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
31f90 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
31fa0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
31fb0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
31fc0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
31fd0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
31fe0 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
31ff0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
32000 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
32010 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
32020 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
32030 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
32040 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
32050 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
32060 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
32070 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
32080 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
32090 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
320a0 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
320b0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
320c0 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
320d0 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
320e0 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
320f0 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
32100 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
32110 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
32120 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
32130 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
32140 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
32150 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
32160 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
32170 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
32180 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
32190 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
321a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
321b0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
321c0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
321d0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
321e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
321f0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
32200 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
32210 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
32220 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
32230 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49  t*, int N);.SQLI
32240 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32250 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32260 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32270 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
32280 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
32290 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
322a0 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
322b0 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
322c0 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
322d0 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
322e0 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
322f0 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
32300 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
32310 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
32320 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
32330 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
32340 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32350 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74  _blob()].  ^If t
32360 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
32370 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
32380 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
32390 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
323a0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
323b0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
323c0 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
323d0 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
323e0 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
323f0 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20  royed.  ^The.** 
32400 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
32410 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
32420 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
32430 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
32440 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
32450 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
32460 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
32470 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
32480 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
32490 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
324a0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
324b0 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
324c0 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
324d0 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
324e0 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
324f0 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
32500 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
32510 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
32520 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
32530 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
32540 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
32550 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
32560 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
32570 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
32580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
32590 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
325a0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
325b0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
325c0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
325d0 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
325e0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
325f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32600 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
32610 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
32620 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
32630 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
32640 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
32650 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
32660 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
32670 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
32680 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
32690 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
326a0 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
326b0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
326c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
326d0 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
326e0 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
326f0 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
32700 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
32710 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
32720 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
32730 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
32740 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
32750 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
32760 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
32770 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
32780 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
32790 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
327a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
327b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
327c0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
327d0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
327e0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
327f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32800 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
32810 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
32820 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
32830 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
32840 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
32850 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
32860 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
32870 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
32880 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
32890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
328a0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
328b0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
328c0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
328d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
328e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
328f0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
32900 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
32910 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
32920 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
32930 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
32940 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
32950 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
32960 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
32970 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
32980 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
32990 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
329a0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
329b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
329c0 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
329d0 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
329e0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
329f0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
32a00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32a10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
32a20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
32a30 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
32a40 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
32a50 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
32a60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
32a70 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
32a80 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
32a90 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
32aa0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
32ab0 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
32ac0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
32ad0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
32ae0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32af0 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
32b00 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
32b10 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
32b20 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
32b30 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
32b40 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
32b50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32b60 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
32b70 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
32b80 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
32b90 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
32ba0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
32bb0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
32bc0 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
32bd0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
32be0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
32bf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32c00 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
32c10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32c20 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
32c30 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
32c40 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
32c50 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
32c60 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
32c70 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
32c80 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
32c90 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
32ca0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
32cb0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
32cc0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
32cd0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
32ce0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
32cf0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
32d00 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
32d10 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
32d20 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
32d30 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
32d40 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
32d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32d60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
32d70 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
32d80 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
32d90 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
32da0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
32db0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
32dc0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
32dd0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
32de0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
32df0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
32e00 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
32e10 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
32e20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
32e30 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
32e40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32e50 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
32e60 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
32e70 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
32e80 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
32e90 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
32ea0 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
32eb0 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
32ec0 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
32ed0 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
32ee0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
32ef0 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
32f00 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
32f10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
32f20 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
32f30 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
32f40 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
32f50 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
32f60 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
32f70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32f80 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
32f90 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
32fa0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
32fb0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
32fc0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
32fd0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
32fe0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
32ff0 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
33000 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33010 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
33020 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
33030 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
33040 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
33050 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
33060 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
33070 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
33080 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33090 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
330a0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
330b0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
330c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
330d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
330e0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
330f0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
33100 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
33110 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
33120 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
33130 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
33140 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
33150 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
33160 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
33170 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33180 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
33190 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
331a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
331b0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
331c0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
331d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
331e0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
331f0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
33200 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
33210 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
33220 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33230 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
33240 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33250 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
33260 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
33270 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
33280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33290 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
332a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
332b0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
332c0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
332d0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
332e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
332f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33300 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
33310 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
33320 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
33330 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
33340 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
33350 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
33360 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
33370 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
33380 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
33390 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
333a0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
333b0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
333c0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
333d0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
333e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
333f0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
33400 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
33410 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
33420 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
33430 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
33440 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
33450 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
33460 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
33470 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
33480 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
33490 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
334a0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
334b0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
334c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
334d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
334e0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
334f0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
33500 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
33510 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
33520 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
33530 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
33540 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
33550 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
33560 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
33570 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
33580 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
33590 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
335a0 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
335b0 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
335c0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
335d0 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
335e0 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
335f0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
33600 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
33610 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
33620 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
33630 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
33640 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
33650 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
33660 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
33670 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
33680 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
33690 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
336a0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
336b0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
336c0 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
336d0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
336e0 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
336f0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
33700 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
33710 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
33720 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
33730 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
33740 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
33750 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
33760 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
33770 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
33780 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
33790 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
337a0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
337b0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
337c0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
337d0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
337e0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
337f0 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
33800 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
33810 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
33820 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
33830 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33850 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
33860 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
33870 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
33880 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
33890 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
338a0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
338b0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
338c0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
338d0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
338e0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
338f0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
33900 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
33910 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
33920 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
33930 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
33940 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
33950 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
33960 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
33970 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
33980 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
33990 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
339a0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
339b0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
339c0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
339d0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
339e0 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
339f0 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
33a00 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
33a10 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
33a20 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
33a30 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
33a40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33a50 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
33a60 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
33a70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
33a80 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
33a90 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
33aa0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
33ab0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33ac0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
33ad0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
33ae0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33af0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
33b00 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
33b10 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
33b20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
33b30 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
33b40 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
33b50 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
33b60 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
33b70 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
33b80 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
33b90 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
33ba0 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
33bb0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
33bc0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
33bd0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
33be0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
33bf0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
33c00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
33c10 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
33c20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
33c30 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
33c40 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
33c50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33c60 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
33c70 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
33c80 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
33c90 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
33ca0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
33cb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
33cc0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
33cd0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
33ce0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
33cf0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
33d00 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
33d10 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
33d20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33d30 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
33d40 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
33d50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
33d60 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
33d70 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
33d80 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
33d90 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
33da0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
33db0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33dc0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
33dd0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
33de0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
33df0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33e00 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
33e10 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
33e20 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  e);.SQLITE_API v
33e30 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33e40 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
33e50 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33e60 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51   char*, int);.SQ
33e70 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
33e80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33e90 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
33ea0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
33eb0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
33ec0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
33ed0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
33ee0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
33ef0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
33f00 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
33f10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
33f20 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
33f30 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
33f40 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
33f50 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
33f60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33f70 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
33f80 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
33f90 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
33fa0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33fb0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
33fc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33fd0 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
33fe0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
33ff0 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
34000 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34010 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
34020 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
34030 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
34040 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34050 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
34060 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
34070 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
34080 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
34090 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
340a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
340b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
340c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
340d0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
340e0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
340f0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
34100 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
34110 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34120 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
34130 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
34140 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
34150 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34160 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
34170 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34180 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
34190 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
341a0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
341b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
341c0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
341d0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
341e0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
341f0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
34200 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
34210 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34220 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
34230 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
34240 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
34250 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
34260 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
34270 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
34280 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
34290 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
342a0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
342b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
342c0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
342d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
342e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
342f0 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
34300 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
34310 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
34320 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34330 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
34340 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34350 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
34360 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
34370 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
34380 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
34390 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
343a0 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
343b0 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
343c0 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
343d0 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
343e0 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
343f0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
34400 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
34410 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
34420 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
34430 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
34440 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
34450 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
34460 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
34470 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
34480 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
34490 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
344a0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
344b0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
344c0 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
344d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
344e0 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
344f0 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
34500 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
34510 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
34520 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
34530 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
34540 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
34550 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
34560 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
34570 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
34580 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
34590 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
345a0 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
345b0 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
345c0 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
345d0 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
345e0 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
345f0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
34600 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
34610 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
34620 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
34630 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
34640 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
34650 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
34660 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
34670 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
34680 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
34690 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
346a0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
346b0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
346c0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
346d0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
346e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
346f0 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
34700 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
34710 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
34720 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
34730 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
34740 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
34750 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
34760 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
34770 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
34780 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
34790 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
347a0 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
347b0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
347c0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
347d0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
347e0 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
347f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
34800 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
34810 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
34820 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
34830 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
34840 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
34850 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
34860 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
34870 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
34880 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
34890 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
348a0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
348b0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
348c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
348d0 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
348e0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
348f0 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
34900 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
34910 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
34920 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
34930 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
34940 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
34950 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
34960 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
34970 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
34980 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
34990 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
349a0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
349b0 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
349c0 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
349d0 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
349e0 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
349f0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
34a00 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
34a10 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
34a20 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
34a30 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
34a40 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
34a50 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
34a60 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
34a70 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
34a80 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
34a90 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
34aa0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
34ab0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
34ac0 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
34ad0 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
34ae0 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
34af0 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
34b00 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
34b10 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
34b20 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
34b30 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
34b40 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
34b50 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
34b60 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
34b70 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
34b80 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
34b90 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
34ba0 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
34bb0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
34bc0 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
34bd0 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
34be0 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
34bf0 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
34c00 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
34c10 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
34c20 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
34c30 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
34c40 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
34c50 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
34c60 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
34c70 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
34c80 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
34c90 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
34ca0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
34cb0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
34cc0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
34cd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34ce0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34cf0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
34d00 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
34d10 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
34d20 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
34d30 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
34d40 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
34d50 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
34d60 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
34d70 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34d80 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
34d90 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
34da0 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
34db0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
34dc0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
34dd0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
34de0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
34df0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
34e00 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
34e10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34e20 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
34e30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
34e40 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
34e50 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
34e60 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
34e70 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
34e80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
34e90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34ea0 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
34eb0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
34ec0 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
34ed0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34ee0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
34ef0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
34f00 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
34f10 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
34f20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
34f30 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
34f40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
34f50 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
34f60 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
34f70 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
34f80 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
34f90 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
34fa0 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
34fb0 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
34fc0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
34fd0 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
34fe0 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
34ff0 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
35000 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
35010 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
35020 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
35030 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
35040 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
35050 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
35060 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
35070 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
35080 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
35090 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
350a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
350b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
350c0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
350d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
350e0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
350f0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
35100 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
35110 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
35120 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
35130 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51  nst void*).);.SQ
35140 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
35150 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35160 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
35170 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
35180 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
35190 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
351a0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
351b0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
351c0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
351d0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
351e0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
351f0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
35200 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35210 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35220 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
35230 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
35240 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
35250 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
35260 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
35270 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
35280 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
35290 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
352a0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
352b0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
352c0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
352d0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
352e0 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
352f0 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
35300 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
35310 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
35320 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
35330 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
35340 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
35350 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
35360 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
35370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35380 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
35390 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
353a0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
353b0 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
353c0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
353d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
353e0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
353f0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
35400 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
35410 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
35420 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
35430 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
35440 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
35450 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
35460 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
35470 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
35480 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35490 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
354a0 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
354b0 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
354c0 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
354d0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
354e0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
354f0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
35500 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
35510 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
35520 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
35530 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
35540 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
35550 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
35560 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
35570 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
35580 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
35590 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
355a0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
355b0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
355c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
355d0 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
355e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
355f0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
35600 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
35610 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
35620 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
35630 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
35640 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
35650 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
35660 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
35670 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
35680 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
35690 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
356a0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
356b0 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
356c0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
356d0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
356e0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
356f0 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
35700 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
35710 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
35720 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
35730 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
35740 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
35750 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35760 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
35770 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35780 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
35790 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
357a0 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
357b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
357c0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
357d0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
357e0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
357f0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
35800 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
35810 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
35820 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  r*).);.SQLITE_AP
35830 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
35840 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
35850 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
35860 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
35870 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
35880 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
35890 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
358a0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
358b0 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
358c0 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
358d0 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
358e0 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
358f0 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
35900 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
35910 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
35920 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
35930 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
35940 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
35950 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
35960 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
35970 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
35980 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
35990 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
359a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
359b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
359c0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
359d0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
359e0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
359f0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
35a00 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
35a10 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
35a20 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
35a30 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
35a40 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
35a50 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
35a60 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
35a70 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
35a80 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
35a90 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
35aa0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
35ab0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
35ac0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
35ad0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
35ae0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
35af0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
35b00 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
35b10 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
35b20 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
35b30 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
35b40 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
35b50 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
35b60 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
35b70 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
35b80 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
35b90 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
35ba0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
35bb0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
35bc0 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
35bd0 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
35be0 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
35bf0 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
35c00 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
35c10 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53   will work..*/.S
35c20 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35c30 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
35c40 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
35c50 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
35c60 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
35c70 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
35c80 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
35c90 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
35ca0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
35cb0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
35cc0 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
35cd0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
35ce0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
35cf0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
35d00 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
35d10 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
35d20 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35d30 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
35d40 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
35d50 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
35d60 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
35d70 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
35d80 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
35d90 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
35da0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
35db0 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
35dc0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
35dd0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
35de0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
35df0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
35e00 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
35e10 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
35e20 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
35e30 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
35e40 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
35e50 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
35e60 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
35e70 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
35e80 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
35e90 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
35ea0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
35eb0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
35ec0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
35ed0 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
35ee0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
35ef0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
35f00 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
35f10 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
35f20 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
35f30 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
35f40 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
35f50 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
35f60 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
35f70 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
35f80 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
35f90 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
35fa0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
35fb0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
35fc0 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20  If the xSleep() 
35fd0 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
35fe0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
35ff0 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
36000 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f  correctly, or no
36010 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74  t implemented at
36020 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68  .** all, then th
36030 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
36040 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61  lite3_sleep() ma
36050 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74  y deviate from t
36060 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a  he description.*
36070 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  * in the previou
36080 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f  s paragraphs..*/
36090 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
360a0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
360b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
360c0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
360d0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
360e0 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
360f0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
36100 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
36110 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
36120 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
36130 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
36140 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
36150 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
36160 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
36170 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
36180 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
36190 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
361a0 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
361b0 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
361c0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
361d0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
361e0 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
361f0 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
36200 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
36210 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
36220 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
36230 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
36240 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
36250 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
36260 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
36270 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
36280 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
36290 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
362a0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
362b0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
362c0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
362d0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
362e0 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
362f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36300 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
36310 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
36320 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
36330 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
36340 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
36350 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
36360 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
36370 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
36380 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
36390 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
363a0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
363b0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
363c0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
363d0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
363e0 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
363f0 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
36400 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
36410 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
36420 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
36430 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
36440 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
36450 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
36460 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
36470 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
36480 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
36490 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
364a0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
364b0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
364c0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
364d0 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
364e0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
364f0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
36500 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
36510 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
36520 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
36530 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
36540 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
36550 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
36560 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
36570 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
36580 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
36590 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
365a0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
365b0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
365c0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
365d0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
365e0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
365f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
36600 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
36610 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
36620 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
36630 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
36640 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
36650 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
36660 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
36670 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
36680 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
36690 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
366a0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
366b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
366c0 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  n] or [sqlite3_o
366d0 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77  pen_v2].  Otherw
366e0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
366f0 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
36700 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
36710 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
36720 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65   may fail.  Here
36730 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c   is an.** exampl
36740 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74  e of how to do t
36750 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69  his using C++ wi
36760 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52  th the Windows R
36770 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62  untime:.**.** <b
36780 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
36790 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68  ** LPCWSTR zPath
367a0 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72   = Windows::Stor
367b0 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e  age::Application
367c0 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a  Data::Current->.
367d0 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65  ** &nbsp;     Te
367e0 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50  mporaryFolder->P
367f0 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20  ath->Data();.** 
36800 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 23 39  char zPathBuf&#9
36810 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23  1;MAX_PATH + 1&#
36820 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a  93;;.** memset(z
36830 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65  PathBuf, 0, size
36840 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a  of(zPathBuf));.*
36850 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74  * WideCharToMult
36860 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30  iByte(CP_UTF8, 0
36870 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61  , zPath, -1, zPa
36880 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50  thBuf, sizeof(zP
36890 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73  athBuf),.** &nbs
368a0 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c  p;     NULL, NUL
368b0 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  L);.** sqlite3_t
368c0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20  emp_directory = 
368d0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
368e0 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b  "%s", zPathBuf);
368f0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
36900 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54  kquote>.*/.SQLIT
36910 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54  E_API SQLITE_EXT
36920 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
36930 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
36940 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36950 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
36960 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44 61  older Holding Da
36970 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a  tabase Files.**.
36980 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
36990 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
369a0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
369b0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
369c0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
369d0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
369e0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
369f0 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73 65  hen all database
36a00 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66   files.** specif
36a10 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61 74  ied with a relat
36a20 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e 64  ive pathname and
36a30 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63 65   created or acce
36a40 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74  ssed by.** SQLit
36a50 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62  e when using a b
36a60 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20  uilt-in windows 
36a70 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
36a80 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73 75  FS] will be assu
36a90 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c  med.** to be rel
36aa0 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64 69  ative to that di
36ab0 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74  rectory.)^ ^If t
36ac0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
36ad0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
36ae0 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  r, then SQLite a
36af0 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c 20  ssumes that all 
36b00 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 73  database files s
36b10 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74 68  pecified.** with
36b20 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
36b30 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69 76  name are relativ
36b40 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  e to the current
36b50 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f   directory.** fo
36b60 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20 20  r the process.  
36b70 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77 73  Only the windows
36b80 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20 6f   VFS makes use o
36b90 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a  f this global.**
36ba0 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69 73   variable; it is
36bb0 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65 20   ignored by the 
36bc0 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  unix VFS..**.** 
36bd0 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61 6c  Changing the val
36be0 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69 61  ue of this varia
36bf0 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74 61  ble while a data
36c00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36c10 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72  is.** open can r
36c20 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72 75  esult in a corru
36c30 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a  pt database..**.
36c40 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
36c50 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
36c60 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
36c70 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
36c80 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
36c90 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
36ca0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
36cb0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
36cc0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
36cd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36ce0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
36cf0 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
36d00 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
36d10 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
36d20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
36d30 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
36d40 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
36d50 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
36d60 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
36d70 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
36d80 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
36d90 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
36da0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
36db0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
36dc0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
36dd0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
36de0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
36df0 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64  he [data_store_d
36e00 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
36e10 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
36e20 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
36e30 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
36e40 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
36e50 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
36e60 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
36e70 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
36e80 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64  he [data_store_d
36e90 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
36ea0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
36eb0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
36ec0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
36ed0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
36ee0 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
36ef0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
36f00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
36f10 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
36f20 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
36f30 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
36f40 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
36f50 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
36f60 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
36f70 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
36f80 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
36f90 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
36fa0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
36fb0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
36fc0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
36fd0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
36fe0 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
36ff0 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
37000 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64  he [data_store_d
37010 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
37020 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
37030 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
37040 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
37050 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 61  char *sqlite3_da
37060 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  ta_directory;../
37070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
37080 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
37090 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57  mit Mode.** KEYW
370a0 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
370b0 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54  t mode}.**.** ^T
370c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
370d0 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
370e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
370f0 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
37100 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
37110 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37120 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
37130 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
37140 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
37150 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69  ely.  ^Autocommi
37160 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
37170 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74  default..** ^Aut
37180 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
37190 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
371a0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
371b0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
371c0 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
371d0 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
371e0 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
371f0 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
37200 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
37210 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
37220 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
37230 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
37240 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
37250 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
37260 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
37270 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
37280 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
37290 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
372a0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
372b0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
372c0 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
372d0 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
372e0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
372f0 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
37300 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
37310 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
37320 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
37330 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
37340 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
37350 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
37360 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
37370 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
37380 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
37390 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
373a0 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
373b0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
373c0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
373d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
373e0 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
373f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
37400 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
37410 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
37420 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
37430 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
37440 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37450 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
37460 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
37470 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
37480 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ement.**.** ^The
37490 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
374a0 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  le interface ret
374b0 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61  urns the [databa
374c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
374d0 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63  andle.** to whic
374e0 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  h a [prepared st
374f0 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
37500 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73  .  ^The [databas
37510 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
37520 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
37530 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
37540 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  s the same [data
37550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37560 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65  .** that was the
37570 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
37580 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
37590 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
375a0 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61   call (or its va
375b0 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73  riants) that was
375c0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61   used to.** crea
375d0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
375e0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
375f0 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ace..*/.SQLITE_A
37600 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  PI sqlite3 *sqli
37610 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
37620 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
37630 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
37640 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61  eturn The Filena
37650 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61 73  me For A Databas
37660 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
37670 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37680 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29  db_filename(D,N)
37690 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
376a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
376b0 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73  a filename.** as
376c0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64 61  sociated with da
376d0 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e  tabase N of conn
376e0 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20  ection D.  ^The 
376f0 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
37700 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61  le.** has the na
37710 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74  me "main".  If t
37720 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63  here is no attac
37730 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f  hed database N o
37740 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
37750 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  * connection D, 
37760 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20 4e  or if database N
37770 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20   is a temporary 
37780 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  or in-memory dat
37790 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61  abase, then.** a
377a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
377b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
377c0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72   ^The filename r
377d0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
377e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20  function is the 
377f0 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a  output of the.**
37800 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d   xFullPathname m
37810 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46  ethod of the [VF
37820 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20 77  S].  ^In other w
37830 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e 61  ords, the filena
37840 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e  me.** will be an
37850 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e 61   absolute pathna
37860 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20  me, even if the 
37870 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a  filename used.**
37880 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
37890 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79  abase originally
378a0 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 72 65   was a URI or re
378b0 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 2e  lative pathname.
378c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
378d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
378e0 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73  e3_db_filename(s
378f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73  qlite3 *db, cons
37900 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29  t char *zDbName)
37910 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37920 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20  F: Determine if 
37930 61 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  a database is re
37940 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  ad-only.**.** ^T
37950 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  he sqlite3_db_re
37960 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65  adonly(D,N) inte
37970 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20  rface returns 1 
37980 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
37990 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69  N.** of connecti
379a0 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c  on D is read-onl
379b0 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 72 65  y, 0 if it is re
379c0 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20  ad/write, or -1 
379d0 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  if N is not.** t
379e0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74  he name of a dat
379f0 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74  abase on connect
37a00 69 6f 6e 20 44 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ion D..*/.SQLITE
37a10 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
37a20 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  _db_readonly(sql
37a30 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20  ite3 *db, const 
37a40 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a  char *zDbName);.
37a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37a60 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
37a70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37a80 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
37a90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37aa0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
37ab0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
37ac0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
37ad0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
37ae0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
37af0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37b00 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
37b10 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
37b20 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
37b30 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
37b40 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
37b50 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
37b60 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
37b70 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
37b80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37b90 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
37ba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
37bb0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
37bc0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
37bd0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
37be0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
37bf0 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
37c00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
37c10 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
37c20 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
37c30 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
37c40 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
37c50 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
37c60 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
37c70 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
37c80 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
37c90 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53  LL pointer..*/.S
37ca0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
37cb0 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
37cc0 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
37cd0 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
37ce0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
37cf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
37d00 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
37d10 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
37d20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
37d30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
37d40 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
37d50 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
37d60 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
37d70 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
37d80 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
37d90 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43  ransaction is [C
37da0 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65  OMMIT | committe
37db0 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  d]..** ^Any call
37dc0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
37dd0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
37de0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
37df0 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
37e00 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
37e10 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
37e20 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20  ridden..** ^The 
37e30 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37e40 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
37e50 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
37e60 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
37e70 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
37e80 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
37e90 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c  saction is [ROLL
37ea0 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61  BACK | rolled ba
37eb0 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ck]..** ^Any cal
37ec0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
37ed0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
37ee0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37ef0 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
37f00 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
37f10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
37f20 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
37f30 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
37f40 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
37f50 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
37f60 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ck..** ^If the c
37f70 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
37f80 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
37f90 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
37fa0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
37fb0 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
37fc0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
37fd0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
37fe0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
37ff0 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73  ook(D,C,P) and s
38000 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
38010 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
38020 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20  tions.** return 
38030 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
38040 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
38050 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d   call of the sam
38060 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e  e function.** on
38070 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
38080 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38090 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
380a0 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
380b0 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69   for each functi
380c0 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54  on on D..**.** T
380d0 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f  he commit and ro
380e0 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c  llback hook call
380f0 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65  backs are not re
38100 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20  entrant..** The 
38110 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65  callback impleme
38120 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
38130 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
38140 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
38150 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
38160 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
38170 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
38180 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ck.  Any actions
38190 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
381a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
381b0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
381c0 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
381d0 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
381e0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
381f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
38200 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
38210 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f   the commit.** o
38220 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  r rollback hook 
38230 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
38240 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ce..** Note that
38250 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68   running any oth
38260 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  er SQL statement
38270 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c  s, including SEL
38280 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a  ECT statements,.
38290 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c  ** or merely cal
382a0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
382b0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
382c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
382d0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
382e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
382f0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
38300 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
38310 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
38320 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52  agraph..**.** ^R
38330 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
38340 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
38350 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
38360 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ..**.** ^When th
38370 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
38380 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
38390 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
383a0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
383b0 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
383c0 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
383d0 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65  rmally.  ^If the
383e0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20   commit hook.** 
383f0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
38400 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d  , then the [COMM
38410 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64  IT] is converted
38420 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43   into a [ROLLBAC
38430 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  K]..** ^The roll
38440 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76  back hook is inv
38450 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61  oked on a rollba
38460 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  ck that results 
38470 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a  from a commit.**
38480 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20   hook returning 
38490 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61  non-zero, just a
384a0 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69  s it would be wi
384b0 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c  th any other rol
384c0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  lback..**.** ^Fo
384d0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
384e0 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
384f0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
38500 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a  d to have been.*
38510 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
38520 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
38530 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
38540 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
38550 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
38560 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
38570 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
38580 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
38590 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
385a0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
385b0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
385c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
385d0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
385e0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
385f0 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
38600 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
38610 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  losed..**.** See
38620 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
38630 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
38640 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
38650 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
38660 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
38670 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
38680 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
38690 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  id*);.SQLITE_API
386a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72   void *sqlite3_r
386b0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
386c0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
386d0 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
386e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
386f0 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
38700 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
38710 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
38720 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
38730 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
38740 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
38750 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
38760 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
38770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
38780 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
38790 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
387a0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
387b0 20 77 68 65 6e 65 76 65 72