System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 5cf1113f630469aa7acf28a146162ee8bf2209b4:


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 2e 31 22 0a 23 64 65 66 69 6e 65  .7.16.1".#define
1030: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1040: 4e 55 4d 42 45 52 20 33 30 30 37 30 31 36 0a 23  NUMBER 3007016.#
1050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f  define SQLITE_SO
1060: 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30  URCE_ID      "20
1070: 31 33 2d 30 33 2d 32 39 20 31 33 3a 34 34 3a 33  13-03-29 13:44:3
1080: 34 20 35 32 37 32 33 31 62 63 36 37 32 38 35 66  4 527231bc67285f
1090: 30 31 66 62 31 38 64 34 34 35 31 62 32 38 66 36  01fb18d4451b28f6
10a0: 31 64 61 33 63 34 65 33 39 64 22 0a 0a 2f 2a 0a  1da3c4e39d"../*.
10b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
10c0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
10d0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
10e0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
10f0: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69  e3_version, sqli
1100: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
1110: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
1120: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
1130: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
1140: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
1150: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1160: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1170: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1180: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
1190: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
11a0: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
11b0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
11c0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
11d0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
11e0: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
11f0: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
1200: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
1210: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
1220: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
1230: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
1240: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
1250: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1260: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1270: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1280: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
1290: 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65   and thus insure
12a0: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
12b0: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
12c0: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
12d0: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
12e0: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
12f0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1300: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
1310: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1320: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
1330: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1340: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
1350: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1360: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1370: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1380: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1390: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
13b0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
13c0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
13d0: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
13e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
13f0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
1400: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
1410: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
1420: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
1430: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
1440: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1450: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1460: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1470: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
1480: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
1490: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
14a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
14b0: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
14c0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
14d0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
14e0: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
14f0: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
1500: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
1510: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
1520: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
1530: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
1540: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
1550: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
1560: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1570: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
1580: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
1590: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
15a0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
15b0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
15c0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
15d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
15e0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
15f0: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1600: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1610: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1620: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1630: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
1640: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1650: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
1660: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
1670: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
1680: 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45  _API SQLITE_EXTE
1690: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
16a0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
16b0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
16c0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
16d0: 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29  libversion(void)
16e0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
16f0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1700: 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b  _sourceid(void);
1710: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1720: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1730: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1740: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1750: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
1760: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
1770: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1780: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1790: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
17a0: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
17b0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
17c0: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
17d0: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
17e0: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
17f0: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1800: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1810: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
1820: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
1830: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
1840: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
1850: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
1860: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1870: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1880: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1890: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
18a0: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
18b0: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
18c0: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
18d0: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
18e0: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
18f0: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1900: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1910: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
1920: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
1930: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
1940: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
1950: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1960: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
1970: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1980: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1990: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
19a0: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
19b0: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
19c0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
19d0: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
19e0: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
19f0: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1a00: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1a10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1a20: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
1a30: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a40: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
1a50: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
1a60: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
1a70: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a80: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a90: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1aa0: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1ab0: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1ac0: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1ae0: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1af0: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1b00: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1b10: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1b20: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1b30: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1b40: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b50: 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  AGS.SQLITE_API i
1b60: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
1b70: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1b80: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1b90: 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  me);.SQLITE_API 
1ba0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1bb0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1bc0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1be0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1bf0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1c00: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1c10: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c20: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1c30: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1c40: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1c50: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1c60: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1c70: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1c80: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1c90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1ca0: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1cb0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1cc0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1cd0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1ce0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1cf0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1d00: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1d10: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d20: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1d30: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1d40: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1d50: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1d60: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1d70: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1d80: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1d90: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1da0: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1db0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1dc0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1dd0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1de0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1df0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1e00: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1e10: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1e20: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1e30: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1e40: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1e50: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1e60: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1e70: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1e80: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1e90: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1ea0: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1eb0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1ec0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1ed0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1ee0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1ef0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1f00: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1f10: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1f20: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1f30: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
1f40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
1f50: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1f60: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1f70: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1f80: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1f90: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1fa0: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1fb0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1fc0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1fd0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1fe0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1ff0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
2000: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2010: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2020: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2030: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2040: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2050: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2060: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2070: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2080: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2090: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
20a0: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
20b0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
20c0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
20d0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
20e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
20f0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
2100: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2110: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2120: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2130: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2140: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2150: 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20  _MUTEX].  ^(The 
2160: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2170: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
2180: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
2190: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
21a0: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
21b0: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
21c0: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
21d0: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
21e0: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
21f0: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
2200: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
2210: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
2220: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
2230: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2240: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
2250: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
2260: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
2270: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
2280: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
2290: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
22a0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
22b0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
22c0: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
22d0: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
22e0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
22f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
2300: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
2310: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
2320: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
2330: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2340: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
2350: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
2360: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
2370: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
2380: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
2390: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
23a0: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
23b0: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
23c0: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
23d0: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
23e0: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
23f0: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
2400: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
2410: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
2420: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2430: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2450: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
2460: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
2470: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
2480: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61  e3_close()].** a
2490: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
24a0: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20  e_v2()] are its 
24b0: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68  destructors.  Th
24c0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
24d0: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
24e0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
24f0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
2510: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2520: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2530: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
2540: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
2550: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
2560: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
2570: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
2580: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2590: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
25a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25b0: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
25c0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
25d0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
25e0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
25f0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
2600: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
2610: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
2620: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
2630: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
2640: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
2650: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
2660: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
2670: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
2680: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2690: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
26a0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
26b0: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
26c0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
26d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
26e0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
26f0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
2700: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
2710: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2720: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2730: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2740: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2750: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
2760: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2770: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
2780: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
2790: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
27a0: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
27b0: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
27c0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
27d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
27e0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
27f0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
2800: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
2810: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
2820: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
2830: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
2840: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2850: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
2860: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2870: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2880: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2890: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
28a0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
28b0: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
28c0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
28d0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
28e0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
28f0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2900: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2910: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2920: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2930: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2940: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2950: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2960: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2970: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2980: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2990: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
29a0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
29b0: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
29c0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
29d0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
29e0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
29f0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2a00: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2a10: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2a20: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2a30: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2a40: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2a50: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2a60: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2a70: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2a80: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2a90: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2aa0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2ab0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2ac0: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
2ad0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ae0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2af0: 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20  e_v2() routines 
2b00: 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a  are destructors.
2b10: 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  ** for the [sqli
2b20: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  te3] object..** 
2b30: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
2b40: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
2b50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2b60: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
2b70: 4b 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  K if.** the [sql
2b80: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
2b90: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
2ba0: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
2bb0: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73  ssociated.** res
2bc0: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c  ources are deall
2bd0: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ocated..**.** ^I
2be0: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73  onnection is ass
2c00: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66  ociated with unf
2c10: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65  inalized prepare
2c20: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  d.** statements 
2c30: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c40: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a  lite3_backup obj
2c50: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65  ects then sqlite
2c60: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c  3_close().** wil
2c70: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61  l leave the data
2c80: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c90: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20  open and return 
2ca0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
2cb0: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c  * ^If sqlite3_cl
2cc0: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
2cd0: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69  ed with unfinali
2ce0: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61  zed prepared sta
2cf0: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75  tements.** and u
2d00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2d10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
2d20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2d30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
2d40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
2d50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
2d60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2d70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2d80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
2d90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2da0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2db0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
2dc0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
2dd0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
2de0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2df0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
2e00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2e10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
2e20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
2e30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
2e40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
2e50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
2e60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
2e70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
2e80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
2e90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
2ea0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
2eb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2ec0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
2ed0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
2ee0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
2ef0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
2f00: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2f10: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
2f20: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
2f30: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
2f40: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
2f50: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
2f60: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
2f70: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
2f80: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
2f90: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
2fa0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
2fb0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2fc0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
2fd0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2fe0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
2ff0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
3000: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
3010: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
3020: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3030: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
3040: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3050: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
3060: 53 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68  SQLITE_OK but th
3070: 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  e deallocation.*
3080: 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69  * of resources i
3090: 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  s deferred until
30a0: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
30b0: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
30c0: 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61  B handles],.** a
30d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  nd [sqlite3_back
30e0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20  up] objects are 
30f0: 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a  also destroyed..
3100: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71  **.** ^If an [sq
3110: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
3120: 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65   destroyed while
3130: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
3140: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74  s open,.** the t
3150: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75  ransaction is au
3160: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
3170: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
3180: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74  he C parameter t
3190: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
31a0: 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  (C)] and [sqlite
31b0: 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a  3_close_v2(C)].*
31c0: 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
31d0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
31e0: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
31f0: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
3200: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
3210: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
3220: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
3230: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
3240: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
3250: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
3260: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
3270: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
3280: 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71  e3_close() or sq
3290: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
32a0: 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
32b0: 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  nter.** argument
32c0: 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
32d0: 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  o-op..*/.SQLITE_
32e0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32f0: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b  close(sqlite3*);
3300: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
3310: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3320: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3330: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3340: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3350: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3360: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3370: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
3380: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
3390: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
33a0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
33b0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
33c0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
33d0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
33e0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
33f0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3400: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3410: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3420: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3430: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3440: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
3450: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
3460: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
3470: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
3480: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
3490: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
34a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
34b0: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
34c0: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
34d0: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
34e0: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
34f0: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3500: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3510: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3520: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3530: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3540: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
3550: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
3560: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
3570: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
3580: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
3590: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
35a0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
35b0: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
35c0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
35d0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
35e0: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
35f0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3600: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3610: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3620: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3630: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3640: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
3650: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
3660: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
3670: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
3680: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
3690: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
36a0: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
36b0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
36c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
36d0: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
36e0: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
36f0: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3700: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3710: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3720: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3730: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3740: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
3750: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
3760: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
3770: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
3780: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
3790: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
37a0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
37b0: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
37c0: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
37d0: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
37e0: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
37f0: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3800: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3810: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3820: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3830: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3840: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
3850: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3860: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3870: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
3880: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
3890: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
38a0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
38b0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
38c0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
38d0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
38e0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
38f0: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3900: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3910: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3920: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3930: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3940: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
3950: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
3960: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
3970: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
3980: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
3990: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
39a0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
39b0: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
39c0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
39d0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
39e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
39f0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3a00: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3a10: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3a20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3a30: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3a40: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
3a50: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
3a60: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
3a70: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
3a80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3a90: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
3aa0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3ab0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3ac0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3ad0: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3ae0: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3af0: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3b00: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3b10: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3b20: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3b30: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3b40: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3b50: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3b60: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3b70: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3b80: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3b90: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3ba0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3bb0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3bc0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3bd0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3be0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3bf0: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3c00: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3c10: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3c20: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3c30: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3c40: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3c50: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3c60: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3c70: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3c80: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3c90: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3ca0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3cb0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3cc0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3cd0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3ce0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3cf0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3d00: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3d10: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3d20: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3d30: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3d40: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3d50: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3d60: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3d70: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3d80: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3d90: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3da0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3db0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3dc0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3dd0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3de0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3df0: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3e00: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3e10: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3e20: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3e30: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3e40: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3e50: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3e60: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3e70: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3e80: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3e90: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3ea0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3eb0: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3ec0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3ed0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3ee0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3ef0: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3f00: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3f10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3f20: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f30: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3f40: 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20 63  lose [database c
3f50: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
3f60: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  fied by.**      
3f70: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3f80: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3f90: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
3fa0: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
3fb0: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ing..** <li> The
3fc0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3fd0: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  t not modify the
3fe0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
3ff0: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  ext passed into.
4000: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20  **      the 2nd 
4010: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
4020: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
4030: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
4040: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
4050: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ul>.*/.SQLITE_
4060: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
4070: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4080: 2c 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 20 20                  
40a0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
40b0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
40c0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
40f0: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4100: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4110: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4120: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4130: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4140: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  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 20 20                  
4170: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4180: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4190: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
41a0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41c0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
41d0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
41e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
41f0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4200: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
4210: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
4220: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
4230: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
4240: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
4250: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
4260: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
4270: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
4280: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
4290: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
42a0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
42b0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
42c0: 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  te success or fa
42d0: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  ilure..**.** New
42e0: 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79   error codes may
42f0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
4300: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
4310: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  SQLite..**.** Se
4320: 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
4330: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
4340: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4350: 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  es],.** [sqlite3
4360: 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
4370: 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c  t()] [SQLITE_ROL
4380: 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63  LBACK | result c
4390: 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  odes]..*/.#defin
43a0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
43b0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
43c0: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
43d0: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
43e0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
43f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4400: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4410: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4420: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
4430: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4440: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
4450: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
4460: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
4470: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
4480: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
4490: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
44a0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
44b0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
44c0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
44d0: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
44e0: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
44f0: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4520: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4530: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
4540: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4550: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
4560: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
4570: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
4580: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4590: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
45a0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
45b0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
45c0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
45d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
45e0: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
45f0: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4600: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4620: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4630: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
4640: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
4650: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4670: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
4680: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
4690: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
46a0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
46b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
46c0: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
46d0: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
46e0: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
46f0: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4700: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4710: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4720: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4730: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
4740: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4750: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
4760: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
4770: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
4780: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
4790: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
47a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
47b0: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
47c0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
47d0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
47e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
47f0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4800: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4810: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4830: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4840: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
4850: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
4860: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4870: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4880: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4890: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
48a0: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
48b0: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
48c0: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
48d0: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
48e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4900: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4910: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4920: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4940: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4950: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4960: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4970: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4980: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4990: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
49a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49b0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
49c0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
49d0: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
49e0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
49f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4a00: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4a10: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4a20: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4a30: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4a40: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
4a50: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
4a60: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
4a70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a80: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4a90: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4aa0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4ab0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ad0: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4ae0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4af0: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4b00: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
4b20: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
4b30: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4b40: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
4b50: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
4b60: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
4b70: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
4b80: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b90: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
4ba0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
4bb0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
4bc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4bd0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
4be0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4bf0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  S: {extended err
4c00: 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64  or code} {extend
4c10: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  ed error codes}.
4c20: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
4c30: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4c40: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65  de} {extended re
4c50: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
4c60: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
4c70: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
4c80: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
4c90: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
4ca0: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 26 integer.** 
4cb0: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
4cc0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4cd0: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4ce0: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4cf0: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4d00: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4d10: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4d20: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4d30: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4d40: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4d50: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4d60: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4d70: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
4d80: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
4d90: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
4da0: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
4db0: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
4dc0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
4dd0: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
4de0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
4df0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
4e00: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
4e10: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
4e20: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
4e30: 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65  errors. The exte
4e40: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4e50: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  s are enabled or
4e60: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
4e70: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
4e80: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
4e90: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
4ea0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
4eb0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
4ec0: 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f  PI..**.** Some o
4ed0: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
4ee0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4ef0: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
4f00: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61   here..** One ma
4f10: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d  y expect the num
4f20: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20  ber of extended 
4f30: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c  result codes wil
4f40: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f  l be expand.** o
4f50: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77  ver time.  Softw
4f60: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78  are that uses ex
4f70: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f80: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63  des should expec
4f90: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20  t.** to see new 
4fa0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20  result codes in 
4fb0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
4fc0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4fd0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72   The SQLITE_OK r
4fe0: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20  esult code will 
4ff0: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65  never be extende
5000: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61  d.  It will alwa
5010: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79  ys.** be exactly
5020: 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e   zero..*/.#defin
5030: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5040: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
5050: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5060: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5070: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5080: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
5090: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50a0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
50b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
50c0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
50d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
50e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
50f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
5100: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
5110: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
5120: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5130: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5140: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5150: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5160: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5170: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
5180: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
5190: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
51a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51b0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
51c0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
51d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
51e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51f0: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
5200: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5210: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
5220: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5230: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5240: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5250: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5260: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5270: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
5280: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5290: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
52a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52b0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
52c0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52d0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
5320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5330: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5340: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5350: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5370: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
5380: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
5390: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
53a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53b0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
53c0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53d0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
53e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53f0: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
5400: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5410: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
5420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5430: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
5440: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5450: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
5460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5470: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
5480: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5490: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
54a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54b0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
54c0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54d0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
54e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54f0: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
5500: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5510: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
5520: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5530: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
5540: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5550: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
5560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5570: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
5580: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5590: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
55a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55b0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
55c0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
55d0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
55e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55f0: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
5600: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
5610: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
5620: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5630: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
5640: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5650: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
5660: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5670: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d  E_CANTOPEN_NOTEM
5680: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54  PDIR      (SQLIT
5690: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c  E_CANTOPEN | (1<
56a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56b0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44  ITE_CANTOPEN_ISD
56c0: 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  IR          (SQL
56d0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
56e0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
56f0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46  QLITE_CANTOPEN_F
5700: 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53  ULLPATH       (S
5710: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5720: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5730: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5740: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5750: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5760: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5770: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5780: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5790: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
57a0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
57c0: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
57d0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
57e0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
57f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5800: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5810: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5820: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5840: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5850: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5860: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5880: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5890: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
58a0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
58b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58c0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
58d0: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
58e0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
58f0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5900: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5910: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5920: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5930: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5940: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5950: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5960: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5970: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5990: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
59a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
59b0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
59c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
59d0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
59e0: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
59f0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5a00: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5a10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5a20: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5a30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5a40: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5a50: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5a60: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5a70: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a80: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5a90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5aa0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5ab0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ac0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5ad0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
5ae0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
5af0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
5b00: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
5b10: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
5b20: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
5b30: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
5b40: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5b50: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5b60: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
5b70: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
5b80: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5b90: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
5ba0: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
5bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5bc0: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
5bd0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
5be0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5bf0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5c00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5c10: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
5c20: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
5c30: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5c40: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5c50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5c60: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
5c70: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
5c80: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5c90: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5cb0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
5cc0: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
5cd0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5cf0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
5d00: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
5d10: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5d30: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
5d40: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
5d50: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5d70: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
5d80: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
5d90: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5da0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5db0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5dc0: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
5dd0: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
5de0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5df0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5e00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5e10: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
5e20: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
5e30: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5e40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5e50: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
5e60: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
5e70: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5e80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5e90: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
5ea0: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
5eb0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5ed0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
5ee0: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
5ef0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5f00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f10: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
5f20: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
5f30: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5f40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f50: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
5f60: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
5f70: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5f80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f90: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
5fa0: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
5fb0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5fc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5fd0: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
5fe0: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
5ff0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6000: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6020: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
6030: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
6040: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6050: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6070: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
6080: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
6090: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
60a0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
60b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
60c0: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
60d0: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
60e0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
60f0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6100: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6110: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
6120: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
6130: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
6140: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
6150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6160: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
6170: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
6180: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
6190: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
61a0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
61b0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
61c0: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
61d0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
61e0: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
61f0: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
6200: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
6210: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
6220: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
6230: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
6240: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
6250: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
6260: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
6270: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
6280: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6290: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
62a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
62b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
62c0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
62d0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
62e0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
62f0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6300: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6310: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6320: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6330: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6340: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6350: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6360: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6370: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6380: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6390: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
63a0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
63b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
63c0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
63d0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
63e0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
63f0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6400: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6410: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6420: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6430: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6440: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6450: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6460: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6470: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6480: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6490: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
64a0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
64b0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
64c0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
64d0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
64e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
64f0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6500: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
6510: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
6520: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
6530: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
6540: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
6550: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
6560: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
6570: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
6580: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
6590: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
65a0: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
65b0: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
65c0: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
65d0: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
65e0: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
65f0: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
6600: 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ed..*/.#define S
6610: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6620: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
6630: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
6640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6650: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
6660: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6670: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
6680: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6690: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
66a0: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
66b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
66c0: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
66d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
66e0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
66f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6700: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6710: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
6720: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6730: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
6740: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
6750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6760: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
6770: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6780: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
6790: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
67a0: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
67b0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
67c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
67d0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
67e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
67f0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
6800: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6810: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
6820: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
6830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6840: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
6850: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6860: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
6870: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6880: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
6890: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
68a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
68b0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
68c0: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30  ITE    0x0000100
68d0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
68e0: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
68f0: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
6900: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6910: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6920: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6930: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
6940: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6950: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6960: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
6970: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
6980: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6990: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
69a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
69b0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
69c0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
69d0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
69e0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
69f0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6a00: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
6a10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
6a20: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
6a30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6a40: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6a50: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6a60: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
6a70: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
6a80: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
6a90: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
6aa0: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
6ab0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
6ac0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6ad0: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
6ae0: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
6af0: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6b00: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
6b10: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
6b20: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
6b30: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
6b40: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
6b50: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
6b60: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
6b70: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
6b80: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
6b90: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
6ba0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6bb0: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
6bc0: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
6bd0: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
6be0: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
6bf0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
6c00: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
6c10: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
6c20: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
6c30: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
6c40: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
6c50: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6c60: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
6c70: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
6c80: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
6c90: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
6ca0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
6cb0: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
6cc0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6cd0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
6ce0: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
6cf0: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
6d00: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
6d10: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
6d20: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
6d30: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
6d40: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
6d50: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
6d60: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
6d70: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
6d80: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
6d90: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
6da0: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
6db0: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
6dc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6dd0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6de0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
6df0: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
6e00: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
6e10: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
6e20: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
6e30: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
6e40: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
6e50: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
6e60: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
6e70: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
6e80: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
6e90: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
6ea0: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
6eb0: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
6ec0: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
6ed0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6ee0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
6ef0: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
6f00: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
6f10: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
6f20: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
6f30: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
6f40: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
6f50: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
6f60: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
6f70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6f80: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
6f90: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
6fa0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
6fb0: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
6fc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
6fd0: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
6fe0: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
6ff0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7000: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
7010: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
7020: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7030: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
7040: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
7050: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
7060: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
7070: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
7080: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
7090: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
70a0: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
70b0: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
70c0: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
70d0: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
70e0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
70f0: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
7100: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
7110: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
7120: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
7130: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7140: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
7150: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
7160: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
7170: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
7180: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
7190: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
71a0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
71b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
71c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
71d0: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
71e0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
71f0: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
7200: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
7210: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
7220: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
7230: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7240: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
7250: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
7260: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
7270: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
7280: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7290: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
72a0: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
72b0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
72c0: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
72d0: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
72e0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
72f0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
7300: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
7310: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
7320: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
7330: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
7340: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
7350: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
7360: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
7370: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
7380: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
7390: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
73a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
73b0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
73c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
73d0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
73e0: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
73f0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
7400: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
7410: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
7420: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
7430: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
7440: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
7450: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
7460: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
7470: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
7480: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
7490: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
74a0: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
74b0: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
74c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
74d0: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
74e0: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
74f0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
7500: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
7510: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
7520: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
7530: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
7540: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
7550: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
7560: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
7570: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7580: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
7590: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
75a0: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
75b0: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
75c0: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
75d0: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
75e0: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
75f0: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
7600: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7610: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
7620: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
7630: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
7640: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
7650: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
7660: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
7670: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
7680: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
7690: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
76a0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
76b0: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
76c0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
76d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
76e0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
76f0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7700: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7710: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
7720: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7730: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7740: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
7750: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7760: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
7770: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
7780: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
7790: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
77a0: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
77b0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
77c0: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
77d0: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
77e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
77f0: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
7800: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
7810: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
7820: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
7830: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
7840: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
7850: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
7860: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
7870: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
7880: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
7890: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
78a0: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
78b0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
78c0: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
78d0: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
78e0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
78f0: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
7900: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
7910: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
7920: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
7930: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
7940: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
7950: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
7960: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
7970: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
7980: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
7990: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
79a0: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
79b0: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
79c0: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
79d0: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
79e0: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
79f0: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
7a00: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
7a10: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
7a20: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
7a30: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
7a40: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
7a50: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
7a60: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
7a70: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
7a80: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
7a90: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
7aa0: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
7ab0: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
7ac0: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
7ad0: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
7ae0: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
7af0: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
7b00: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
7b10: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
7b20: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
7b30: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
7b40: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
7b50: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c  n use..** A [SQL
7b60: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
7b70: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  ATE | list of op
7b80: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
7b90: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
7ba0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
7bb0: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
7bc0: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
7bd0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
7be0: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
7bf0: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
7c00: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
7c10: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
7c20: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
7c30: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
7c40: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
7c50: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
7c60: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
7c70: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
7c80: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
7c90: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
7ca0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
7cb0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
7cc0: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
7cd0: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
7ce0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
7cf0: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
7d00: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
7d10: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
7d20: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
7d30: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
7d40: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
7d50: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
7d60: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
7d70: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
7d80: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
7d90: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
7da0: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
7db0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
7dc0: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
7dd0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7de0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
7df0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7e00: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
7e10: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7e20: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
7e30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7e40: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
7e50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7e60: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
7e70: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7e80: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
7e90: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7ea0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
7eb0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7ec0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
7ed0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7ee0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
7ef0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7f00: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7f10: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
7f20: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7f30: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
7f40: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
7f50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
7f60: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7f70: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
7f80: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
7f90: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
7fa0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7fb0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
7fc0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
7fd0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
7fe0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
7ff0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
8000: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
8010: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
8020: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
8030: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
8040: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8050: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8060: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
8070: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
8080: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
8090: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
80a0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
80b0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
80c0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
80d0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
80e0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
80f0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
8100: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8110: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
8120: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
8130: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
8140: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
8150: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
8160: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
8170: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
8180: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
8190: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
81a0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
81b0: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
81c0: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
81d0: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
81e0: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
81f0: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
8200: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
8210: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8220: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
8230: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
8240: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
8250: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8260: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
8270: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
8280: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
8290: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
82a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
82b0: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
82c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
82d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
82e0: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
82f0: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
8300: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
8310: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8320: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
8330: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
8340: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8350: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8360: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
8370: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
8380: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
8390: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
83a0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
83b0: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
83c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
83d0: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
83e0: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
83f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8400: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
8410: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
8420: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8430: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
8440: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
8450: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8460: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8470: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
8480: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8490: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
84a0: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
84b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
84c0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
84d0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
84e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
84f0: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
8500: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
8510: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
8520: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8530: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8540: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
8550: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
8560: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8570: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8580: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
8590: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
85a0: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
85b0: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
85c0: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
85d0: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
85e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
85f0: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
8600: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
8610: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
8620: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
8630: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
8640: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
8650: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
8660: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
8670: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8680: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8690: 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74   2 */.  /* Addit
86a0: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
86b0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
86c0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
86d0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
86e0: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
86f0: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
8700: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  es.**.** These i
8710: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
8720: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
8730: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8740: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
8750: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
8760: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
8770: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
8780: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8790: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
87a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
87b0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
87c0: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
87d0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
87e0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
87f0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
8800: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8810: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
8820: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
8830: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
8840: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
8850: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
8860: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
8870: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
8880: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
8890: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
88a0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
88b0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
88c0: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
88d0: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
88e0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
88f0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
8900: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
8910: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
8920: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
8930: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
8940: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
8950: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c   defined..** <ul
8960: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
8970: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8980: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
8990: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
89a0: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
89b0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
89c0: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
89d0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
89e0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
89f0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
8a00: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
8a10: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
8a20: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
8a30: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
8a40: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
8a50: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
8a60: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
8a70: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
8a80: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
8a90: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
8aa0: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
8ab0: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
8ac0: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
8ad0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
8ae0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
8af0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
8b00: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
8b10: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8b20: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
8b30: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8b40: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8b50: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8b60: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
8b70: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
8b80: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
8b90: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
8ba0: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
8bb0: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
8bc0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
8bd0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
8be0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
8bf0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8c00: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
8c10: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
8c20: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
8c30: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
8c40: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
8c50: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
8c60: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
8c70: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
8c80: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
8c90: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
8ca0: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
8cb0: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
8cc0: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
8cd0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
8ce0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
8cf0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
8d00: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
8d10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8d20: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
8d30: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8d40: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
8d50: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
8d60: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
8d70: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
8d80: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
8d90: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
8da0: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
8db0: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
8dc0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
8dd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8de0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
8df0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
8e00: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
8e10: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
8e20: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8e30: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
8e40: 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  ].** ^(The [SQLI
8e50: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
8e60: 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73  ITTED] opcode is
8e70: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
8e80: 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69  nally by.** SQLi
8e90: 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61  te and sent to a
8ea0: 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63  ll VFSes in plac
8eb0: 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74  e of a call to t
8ec0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a  he xSync method.
8ed0: 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ** when the data
8ee0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
8ef0: 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  has [PRAGMA sync
8f00: 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20  hronous] set to 
8f10: 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73  OFF.)^.** Some s
8f20: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
8f30: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
8f40: 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70  l in order to op
8f50: 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a  erate correctly.
8f60: 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20  ** when [PRAGMA 
8f70: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
8f80: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8f90: 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75  =OFF] is set, bu
8fa0: 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73  t most .** VFSes
8fb0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
8fc0: 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f  s signal and sho
8fd0: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
8fe0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
8ff0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
9000: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9010: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9020: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9030: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73  his.** opcode as
9040: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9050: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9060: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9070: 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20  alized VFSes.** 
9080: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9090: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
90a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
90b0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
90c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
90d0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
90e0: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
90f0: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
9100: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
9110: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
9120: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
9130: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
9140: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
9150: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
9160: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
9170: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
9180: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
9190: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
91a0: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
91b0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
91c0: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
91d0: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
91e0: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
91f0: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
9200: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
9210: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
9220: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
9230: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
9240: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
9250: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
9260: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
9270: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
9280: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
9290: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
92a0: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
92b0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
92c0: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
92d0: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
92e0: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
92f0: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
9300: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
9310: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
9320: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
9330: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
9340: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
9350: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
9360: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
9370: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
9380: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
9390: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
93a0: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
93b0: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
93c0: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
93d0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
93e0: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
93f0: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
9400: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
9410: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
9420: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
9430: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
9440: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
9450: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
9460: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
9470: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
9480: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
9490: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
94a0: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
94b0: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
94c0: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
94d0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
94e0: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
94f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9500: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
9510: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9520: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
9530: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
9540: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9550: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9560: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
9570: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
9580: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
9590: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
95a0: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
95b0: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
95c0: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
95d0: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
95e0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
95f0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
9600: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
9610: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
9620: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
9630: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
9640: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
9650: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
9660: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
9670: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
9680: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
9690: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
96a0: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
96b0: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
96c0: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
96d0: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
96e0: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
96f0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9700: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
9710: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
9720: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
9730: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
9740: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
9750: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
9760: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
9770: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
9780: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
9790: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
97a0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
97b0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
97c0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
97d0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
97e0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
97f0: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
9800: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
9810: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
9820: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
9830: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
9840: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
9850: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
9860: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
9870: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
9880: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
9890: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
98a0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
98b0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
98c0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
98d0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
98e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
98f0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9900: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
9910: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9920: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9930: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
9940: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
9950: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
9960: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
9970: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
9980: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
9990: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
99a0: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
99b0: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
99c0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
99d0: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
99e0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
99f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9a00: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9a10: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9a20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9a30: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9a40: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9a50: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
9a60: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
9a70: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
9a80: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
9a90: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
9aa0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
9ab0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
9ac0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
9ad0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
9ae0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9af0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9b00: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
9b10: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9b20: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
9b30: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
9b40: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
9b50: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
9b60: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
9b70: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
9b80: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
9b90: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
9ba0: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
9bb0: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
9bc0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
9bd0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
9be0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
9bf0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
9c00: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
9c10: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
9c20: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9c30: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
9c40: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
9c50: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
9c60: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
9c70: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9c80: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
9c90: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
9ca0: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
9cb0: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
9cc0: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
9cd0: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
9ce0: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
9cf0: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
9d00: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
9d10: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
9d20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
9d30: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
9d40: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
9d50: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
9d60: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
9d70: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
9d80: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9d90: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
9da0: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
9db0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
9dc0: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
9dd0: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
9de0: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
9df0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
9e00: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
9e10: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
9e20: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
9e30: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
9e40: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
9e50: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
9e60: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
9e70: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
9e80: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
9e90: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
9ea0: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
9eb0: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
9ec0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
9ed0: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
9ee0: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
9ef0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9f00: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
9f10: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
9f20: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
9f30: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
9f40: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
9f50: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
9f60: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
9f70: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
9f80: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9f90: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
9fa0: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
9fb0: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
9fc0: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
9fd0: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
9fe0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
9ff0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
a000: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a010: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
a020: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
a030: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
a040: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
a050: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
a060: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
a070: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
a080: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
a090: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
a0a0: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
a0b0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
a0c0: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
a0d0: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
a0e0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
a0f0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
a100: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a110: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a120: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
a130: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
a140: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
a150: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
a160: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
a170: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
a180: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
a190: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
a1a0: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
a1b0: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
a1c0: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
a1d0: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
a1e0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
a1f0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
a200: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
a210: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
a220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a230: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a240: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a250: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
a260: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
a270: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
a280: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
a290: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2a0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
a2b0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a2c0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
a2d0: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
a2e0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
a2f0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
a300: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
a310: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
a320: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
a330: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
a340: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66   statement.  ^If
a350: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a360: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a370: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a  control returns.
a380: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f  ** any result co
a390: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  de other than [S
a3a0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51  QLITE_OK] or [SQ
a3b0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
a3c0: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  that means.** th
a3d0: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75  at the VFS encou
a3e0: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20  ntered an error 
a3f0: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74  while handling t
a400: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20  he [PRAGMA] and 
a410: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69  the.** compilati
a420: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41  on of the PRAGMA
a430: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65   fails with an e
a440: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c  rror.  ^The [SQL
a450: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a460: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
a470: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20  l occurs at the 
a480: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61  beginning of pra
a490: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  gma statement an
a4a0: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a  alysis and so.**
a4b0: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f   it is able to o
a4c0: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e  verride built-in
a4d0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a4e0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ents..**.** <li>
a4f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
a500: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20  USYHANDLER]].** 
a510: 5e 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72  ^This file-contr
a520: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
a530: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
a540: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a550: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
a560: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
a570: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
a580: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
a590: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
a5a0: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
a5b0: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
a5c0: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
a5d0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
a5e0: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
a5f0: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
a600: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
a610: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
a620: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
a630: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
a640: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
a650: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
a660: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
a670: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
a680: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
a690: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
a6a0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
a6b0: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
a6c0: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
a6d0: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
a6e0: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
a6f0: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
a700: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
a710: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
a720: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
a730: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
a740: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
a750: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
a760: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
a770: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
a780: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
a790: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a7a0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
a7b0: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
a7c0: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 66  an invoke this f
a7d0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 74 6f 20 68  ile-control to h
a7e0: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
a7f0: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
a800: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
a810: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
a820: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
a830: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
a840: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
a850: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
a860: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
a870: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
a880: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
a890: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
a8a0: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
a8b0: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
a8c0: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
a8d0: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
a8e0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
a8f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
a900: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
a910: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
a920: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
a930: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
a940: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
a950: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
a960: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
a970: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
a980: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
a990: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
a9a0: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
a9b0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
a9c0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
a9d0: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
a9e0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
a9f0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
aa00: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
aa10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
aa20: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
aa30: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
aa40: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
aa50: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
aa60: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
aa70: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
aa80: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
aa90: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
aaa0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
aab0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
aac0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
aad0: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
aae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
aaf0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
ab00: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
ab10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ab20: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
ab30: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
ab40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ab50: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
ab60: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
ab70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ab80: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
ab90: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
aba0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
abb0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
abc0: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
abd0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
abe0: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
abf0: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
ac00: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ac10: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
ac20: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
ac30: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
ac40: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
ac50: 20 20 20 20 20 20 31 36 0a 0a 2f 2a 0a 2a 2a 20        16../*.** 
ac60: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
ac70: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
ac80: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
ac90: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
aca0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
acb0: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
acc0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
acd0: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
ace0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
acf0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
ad00: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
ad10: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
ad20: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
ad30: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
ad40: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
ad50: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
ad60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
ad70: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
ad80: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
ad90: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
ada0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
adb0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
adc0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
add0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
ade0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
adf0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
ae00: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
ae10: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
ae20: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
ae30: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
ae40: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
ae50: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
ae60: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
ae70: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
ae80: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
ae90: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
aea0: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
aeb0: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
aec0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
aed0: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
aee0: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
aef0: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
af00: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
af10: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
af20: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
af30: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
af40: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
af50: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
af60: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
af70: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
af80: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
af90: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
afa0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
afb0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
afc0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
afd0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
afe0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
aff0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
b000: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
b010: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
b020: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
b030: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
b040: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
b050: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
b060: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
b070: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
b080: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
b090: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
b0a0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
b0b0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
b0c0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
b0d0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
b0e0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
b0f0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
b100: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
b110: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
b120: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
b130: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
b140: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
b150: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
b160: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
b170: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
b180: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
b190: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
b1a0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
b1b0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
b1c0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
b1d0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
b1e0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
b1f0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
b200: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
b210: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
b220: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
b230: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
b240: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
b250: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
b260: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
b270: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
b280: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
b290: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
b2a0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
b2b0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
b2c0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
b2d0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
b2e0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
b2f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
b300: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
b310: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
b320: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
b330: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
b340: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
b350: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
b360: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
b370: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
b380: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
b390: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
b3a0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
b3b0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
b3c0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
b3d0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
b3e0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
b3f0: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
b400: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
b410: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
b420: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
b430: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
b440: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
b450: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
b460: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
b470: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
b480: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
b490: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
b4a0: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
b4b0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
b4c0: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
b4d0: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
b4e0: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
b4f0: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
b500: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
b510: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
b520: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
b530: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
b540: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
b550: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
b560: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
b570: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
b580: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
b590: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
b5a0: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
b5b0: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
b5c0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
b5d0: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
b5e0: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
b5f0: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
b600: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
b610: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
b620: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
b630: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
b640: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
b650: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
b660: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
b670: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
b680: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
b690: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
b6a0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
b6b0: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
b6c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
b6d0: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
b6e0: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
b6f0: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
b700: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
b710: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
b720: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
b730: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
b740: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
b750: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
b760: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
b770: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
b780: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
b790: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
b7a0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
b7b0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
b7c0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
b7d0: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
b7e0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
b7f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
b800: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
b810: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
b820: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
b830: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
b840: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
b850: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
b860: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
b870: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
b880: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
b890: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
b8a0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
b8b0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
b8c0: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
b8d0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
b8e0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
b8f0: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
b900: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
b910: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
b920: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
b930: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
b940: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
b950: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
b960: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
b970: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
b980: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
b990: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
b9a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b9b0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
b9c0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b9d0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
b9e0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
b9f0: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
ba00: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ba10: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
ba20: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ba30: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
ba40: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ba50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
ba60: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
ba70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
ba80: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
ba90: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
baa0: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
bab0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
bac0: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
bad0: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
bae0: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
baf0: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
bb00: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
bb10: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
bb20: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
bb30: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
bb40: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
bb50: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
bb60: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
bb70: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
bb80: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
bb90: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
bba0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
bbb0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
bbc0: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
bbd0: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
bbe0: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
bbf0: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
bc00: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
bc10: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
bc20: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
bc30: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
bc40: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
bc50: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
bc60: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
bc70: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
bc80: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
bc90: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
bca0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
bcb0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
bcc0: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
bcd0: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
bce0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
bcf0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
bd00: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
bd10: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
bd20: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
bd30: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
bd40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
bd50: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
bd60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
bd70: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
bd80: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
bd90: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
bda0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
bdb0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
bdc0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
bdd0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
bde0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
bdf0: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
be00: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
be10: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
be20: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
be30: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
be40: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
be50: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
be60: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
be70: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
be80: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
be90: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
bea0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
beb0: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
bec0: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
bed0: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
bee0: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
bef0: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
bf00: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
bf10: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
bf20: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
bf30: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
bf40: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
bf50: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
bf60: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
bf70: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
bf80: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
bf90: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
bfa0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
bfb0: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
bfc0: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
bfd0: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
bfe0: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
bff0: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
c000: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
c010: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
c020: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
c030: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
c040: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
c050: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
c060: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
c070: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
c080: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
c090: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
c0a0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
c0b0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
c0c0: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
c0d0: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
c0e0: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
c0f0: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
c100: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
c110: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
c120: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
c130: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
c140: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
c150: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
c160: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
c170: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
c180: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
c190: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
c1a0: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
c1b0: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
c1c0: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
c1d0: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
c1e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
c1f0: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
c200: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
c210: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
c220: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
c230: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
c240: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
c250: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
c260: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
c270: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
c280: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
c290: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
c2a0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
c2b0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
c2c0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
c2d0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
c2e0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
c2f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
c300: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
c310: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
c320: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
c330: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
c340: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
c350: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
c360: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
c370: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
c380: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
c390: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
c3a0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
c3b0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
c3c0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
c3d0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
c3e0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
c3f0: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
c400: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
c410: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
c420: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
c430: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
c440: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
c450: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
c460: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
c470: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
c480: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
c490: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
c4a0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
c4b0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
c4c0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
c4d0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
c4e0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
c4f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
c500: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
c510: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
c520: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
c530: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
c540: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
c550: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
c560: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
c570: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
c580: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
c590: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
c5a0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
c5b0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
c5c0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
c5d0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
c5e0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
c5f0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
c600: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
c610: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
c620: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
c630: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
c640: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
c650: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
c660: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
c670: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
c680: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
c690: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
c6a0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
c6b0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
c6c0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
c6d0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
c6e0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
c6f0: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
c700: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
c710: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
c720: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
c730: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
c740: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
c750: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
c760: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
c770: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
c780: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
c790: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
c7a0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
c7b0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
c7c0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c7d0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
c7e0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
c7f0: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
c800: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
c810: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
c820: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
c830: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
c840: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
c850: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
c860: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
c870: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c880: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
c890: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
c8a0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
c8b0: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
c8c0: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
c8d0: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
c8e0: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
c8f0: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
c900: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
c910: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
c920: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
c930: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
c940: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
c950: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
c960: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
c970: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
c980: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
c990: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
c9a0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
c9b0: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
c9c0: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
c9d0: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
c9e0: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
c9f0: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
ca00: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
ca10: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
ca20: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
ca30: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
ca40: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
ca50: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
ca60: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
ca70: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
ca80: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
ca90: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
caa0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
cab0: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
cac0: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
cad0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
cae0: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
caf0: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
cb00: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
cb10: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
cb20: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
cb30: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
cb40: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
cb50: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
cb60: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
cb70: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
cb80: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
cb90: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
cba0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
cbb0: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
cbc0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
cbd0: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
cbe0: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
cbf0: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
cc00: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
cc10: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
cc20: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
cc30: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
cc40: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
cc50: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
cc60: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
cc70: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
cc80: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
cc90: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
cca0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
ccb0: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
ccc0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
ccd0: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
cce0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
ccf0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
cd00: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
cd10: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
cd20: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
cd30: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
cd40: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
cd50: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
cd60: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
cd70: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
cd80: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
cd90: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
cda0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
cdb0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
cdc0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
cdd0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
cde0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
cdf0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
ce00: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
ce10: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
ce20: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
ce30: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
ce40: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
ce50: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
ce60: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
ce70: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
ce80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ce90: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
cea0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
ceb0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
cec0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
ced0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
cee0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
cef0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
cf00: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
cf10: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
cf20: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
cf30: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
cf40: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
cf50: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
cf60: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
cf70: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
cf80: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
cf90: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
cfa0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
cfb0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
cfc0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
cfd0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cfe0: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
cff0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
d000: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
d010: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
d020: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
d030: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
d040: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
d050: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d060: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
d070: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
d080: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
d090: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
d0a0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
d0b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
d0c0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
d0d0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
d0e0: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
d0f0: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
d100: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
d110: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
d120: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
d130: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
d140: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
d150: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
d160: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
d170: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
d180: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
d190: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
d1a0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
d1b0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
d1c0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
d1d0: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
d1e0: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
d1f0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
d200: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
d210: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
d220: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
d230: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
d240: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
d250: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
d260: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
d270: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
d280: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
d290: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
d2a0: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
d2b0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
d2c0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
d2d0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
d2e0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
d2f0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
d300: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
d310: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
d320: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
d330: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
d340: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
d350: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
d360: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
d370: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
d380: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
d390: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
d3a0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
d3b0: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
d3c0: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
d3d0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
d3e0: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
d3f0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
d400: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
d410: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
d420: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
d430: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
d440: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
d450: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
d460: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
d470: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
d480: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
d490: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
d4a0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
d4b0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
d4c0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
d4d0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
d4e0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
d4f0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
d500: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
d510: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
d520: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
d530: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
d540: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
d550: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
d560: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
d570: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
d580: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
d590: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
d5a0: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
d5b0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
d5c0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
d5d0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d5e0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
d5f0: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
d600: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
d610: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
d620: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
d630: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
d640: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
d650: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
d660: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
d670: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
d680: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
d690: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
d6a0: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
d6b0: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
d6c0: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
d6d0: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
d6e0: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
d6f0: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
d700: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
d710: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
d720: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
d730: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
d740: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d750: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
d760: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
d770: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
d780: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d790: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
d7a0: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
d7b0: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
d7c0: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
d7d0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
d7e0: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
d7f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d800: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
d810: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
d820: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
d830: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
d840: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
d850: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
d860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d870: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
d880: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
d890: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d8a0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
d8b0: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
d8c0: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
d8d0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
d8e0: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
d8f0: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
d900: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
d910: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
d920: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
d930: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d940: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
d950: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
d960: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
d970: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
d980: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
d990: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d9a0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
d9b0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
d9c0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
d9d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d9e0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
d9f0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
da00: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
da10: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
da20: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
da30: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
da40: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
da50: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
da60: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
da70: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
da80: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
da90: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
daa0: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
dab0: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
dac0: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
dad0: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
dae0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
daf0: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
db00: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
db10: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
db20: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
db30: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
db40: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
db50: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
db60: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
db70: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
db80: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
db90: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
dba0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
dbb0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
dbc0: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
dbd0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
dbe0: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
dbf0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
dc00: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
dc10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
dc20: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
dc30: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
dc40: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
dc50: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
dc60: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
dc70: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
dc80: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
dc90: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
dca0: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
dcb0: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
dcc0: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
dcd0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
dce0: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
dcf0: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
dd00: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
dd10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dd20: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
dd30: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
dd40: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
dd50: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
dd60: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
dd70: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
dd80: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
dd90: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
dda0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
ddb0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
ddc0: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
ddd0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
dde0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
ddf0: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
de00: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
de10: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
de20: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
de30: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
de40: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
de50: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
de60: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
de70: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
de80: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
de90: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
dea0: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
deb0: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
dec0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
ded0: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
dee0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
def0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
df00: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
df10: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
df20: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
df30: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
df40: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
df50: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
df60: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
df70: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
df80: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
df90: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
dfa0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
dfb0: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
dfc0: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
dfd0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
dfe0: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
dff0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
e000: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
e010: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
e020: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
e030: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
e040: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
e050: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
e060: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
e070: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e080: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
e090: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
e0a0: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
e0b0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e0c0: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
e0d0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
e0e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
e0f0: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
e100: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
e110: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e120: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
e130: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
e140: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
e150: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
e160: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
e170: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
e180: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
e190: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e1a0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
e1b0: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
e1c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e1d0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
e1e0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
e1f0: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
e200: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
e210: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
e220: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
e230: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
e240: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
e250: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
e260: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
e270: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
e280: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
e290: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
e2a0: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
e2b0: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
e2c0: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
e2d0: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
e2e0: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
e2f0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
e300: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
e310: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
e320: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
e330: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
e340: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
e350: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
e360: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
e370: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
e380: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
e390: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
e3a0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
e3b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e3c0: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
e3d0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
e3e0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
e3f0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
e400: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
e410: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
e420: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
e430: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
e440: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
e450: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
e460: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
e470: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e480: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
e490: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
e4a0: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
e4b0: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
e4c0: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
e4d0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
e4e0: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
e4f0: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke 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 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
e520: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
e530: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
e540: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
e550: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
e560: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
e570: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
e580: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
e590: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
e5a0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
e5b0: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
e5c0: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
e5d0: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
e5e0: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
e5f0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e600: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
e610: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
e620: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
e630: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
e640: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
e650: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
e660: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
e670: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
e680: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
e690: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
e6a0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
e6b0: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
e6c0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
e6d0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e6e0: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
e6f0: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
e700: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
e710: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
e720: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
e730: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e740: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
e750: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
e760: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
e770: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
e780: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
e790: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
e7a0: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
e7b0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
e7c0: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
e7d0: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
e7e0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e7f0: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
e800: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
e810: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
e820: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
e830: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
e840: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
e850: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
e860: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
e870: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
e880: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
e890: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
e8a0: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
e8b0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
e8c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
e8d0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
e8e0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
e8f0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
e900: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
e910: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
e920: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
e930: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
e940: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
e950: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
e960: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
e970: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
e980: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
e990: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
e9a0: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
e9b0: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
e9c0: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
e9d0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
e9e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
e9f0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
ea00: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
ea10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
ea20: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
ea30: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
ea40: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
ea50: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
ea60: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
ea70: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
ea80: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
ea90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
eaa0: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
eab0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
eac0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
ead0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
eae0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
eaf0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
eb00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eb10: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
eb20: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
eb30: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
eb40: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
eb50: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
eb60: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
eb70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
eb80: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
eb90: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
eba0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
ebb0: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
ebc0: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
ebd0: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
ebe0: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
ebf0: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
ec00: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
ec10: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
ec20: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
ec30: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
ec40: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
ec50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
ec60: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
ec70: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
ec80: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
ec90: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
eca0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ecb0: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
ecc0: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
ecd0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
ece0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ecf0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
ed00: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
ed10: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
ed20: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
ed30: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
ed40: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
ed50: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
ed60: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
ed70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
ed80: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
ed90: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
eda0: 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
edb0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
edc0: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
edd0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
ede0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
edf0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
ee00: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
ee10: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
ee20: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
ee30: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
ee40: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
ee50: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
ee60: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
ee70: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
ee80: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
ee90: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
eea0: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
eeb0: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
eec0: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
eed0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
eee0: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
eef0: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
ef00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
ef10: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
ef20: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
ef30: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
ef40: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
ef50: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
ef60: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
ef70: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
ef80: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ef90: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
efa0: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
efb0: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
efc0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
efd0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
efe0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
eff0: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
f000: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
f010: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
f020: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f030: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
f040: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
f050: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
f060: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
f070: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
f080: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
f090: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
f0a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
f0b0: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
f0c0: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
f0d0: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
f0e0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
f0f0: 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
f100: 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
f110: 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
f120: 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
f130: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
f140: 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
f150: 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
f160: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
f170: 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
f180: 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
f190: 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
f1a0: 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
f1b0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
f1c0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
f1d0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
f1e0: 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
f1f0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f200: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
f210: 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
f220: 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
f230: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
f240: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
f250: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
f260: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
f270: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
f280: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
f290: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
f2a0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
f2b0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f2c0: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
f2d0: 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
f2e0: 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
f2f0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
f300: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
f310: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
f320: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
f330: 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
f340: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
f350: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
f360: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
f370: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
f380: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
f390: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
f3a0: 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  code]..*/.SQLITE
f3b0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
f3c0: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
f3d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f3e0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
f3f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f400: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
f410: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
f420: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
f430: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
f440: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
f450: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
f460: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
f470: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
f480: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
f490: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f4a0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
f4b0: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
f4c0: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
f4d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f4e0: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
f4f0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
f500: 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
f510: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f520: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
f530: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
f540: 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
f550: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
f560: 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
f570: 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
f580: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
f590: 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
f5a0: 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
f5b0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
f5c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
f5d0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
f5e0: 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
f5f0: 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
f600: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
f610: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
f620: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
f630: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
f640: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
f650: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
f660: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
f670: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
f680: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53  successful..*/.S
f690: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
f6a0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
f6b0: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
f6c0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
f6d0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
f6e0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
f6f0: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
f700: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
f710: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
f720: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
f730: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
f740: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
f750: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
f760: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
f770: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
f780: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
f790: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
f7a0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
f7b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
f7c0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
f7d0: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
f7e0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
f7f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
f800: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
f810: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
f820: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
f830: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
f840: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
f850: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
f860: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
f870: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
f880: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
f890: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
f8a0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
f8b0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
f8c0: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
f8d0: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
f8e0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
f8f0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
f900: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
f910: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
f920: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
f930: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
f940: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
f950: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
f960: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
f970: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
f980: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
f990: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
f9a0: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
f9b0: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
f9c0: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
f9d0: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
f9e0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
f9f0: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
fa00: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
fa10: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
fa20: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
fa30: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
fa40: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
fa50: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fa60: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
fa70: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
fa80: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
fa90: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
faa0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
fab0: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
fac0: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
fad0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
fae0: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
faf0: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
fb00: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
fb10: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
fb20: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
fb30: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
fb40: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
fb50: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
fb60: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
fb70: 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
fb80: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
fb90: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
fba0: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
fbb0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
fbc0: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
fbd0: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
fbe0: 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
fbf0: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
fc00: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
fc10: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
fc20: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
fc30: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
fc40: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
fc50: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
fc60: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
fc70: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
fc80: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
fc90: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
fca0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
fcb0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
fcc0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
fcd0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
fce0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
fcf0: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
fd00: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
fd10: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
fd20: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
fd30: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
fd40: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
fd50: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
fd60: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
fd70: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
fd80: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
fd90: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
fda0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
fdb0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
fdc0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
fdd0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fde0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
fdf0: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
fe00: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
fe10: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
fe20: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
fe30: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
fe40: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
fe50: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
fe60: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
fe70: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
fe80: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
fe90: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
fea0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
feb0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
fec0: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
fed0: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
fee0: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
fef0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
ff00: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ff10: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
ff20: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
ff30: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
ff40: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
ff50: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
ff60: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
ff70: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
ff80: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
ff90: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
ffa0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
ffb0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
ffc0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
ffd0: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
ffe0: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
fff0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
10000 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
10010 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
10020 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
10030 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
10040 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
10050 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
10060 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
10070 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
10080 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
10090 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
100a0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
100b0 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
100c0 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
100d0 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
100e0 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
100f0 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
10100 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
10110 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
10120 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
10130 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
10140 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10150 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
10160 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
10170 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
10180 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
10190 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
101a0 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
101b0 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
101c0 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
101d0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
101e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
101f0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
10200 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10210 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
10220 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
10230 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
10240 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
10250 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
10260 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
10270 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
10280 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
10290 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
102a0 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
102b0 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
102c0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
102d0 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
102e0 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
102f0 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
10300 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
10310 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
10320 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
10330 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
10340 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
10350 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
10360 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
10370 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
10380 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
10390 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
103a0 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
103b0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
103c0 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
103d0 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
103e0 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
103f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
10400 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
10410 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
10420 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
10430 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
10440 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
10450 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
10460 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
10470 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
10480 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
10490 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
104a0 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
104b0 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
104c0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
104d0 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
104e0 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
104f0 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
10500 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
10510 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
10520 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
10530 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
10540 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
10550 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
10560 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
10570 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
10580 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
10590 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
105a0 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
105b0 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
105c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
105d0 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
105e0 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
105f0 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
10600 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10610 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
10620 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
10630 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10640 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on}.**.** These 
10650 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
10660 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
10670 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
10680 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
10690 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
106a0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
106b0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
106c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
106d0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
106e0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
106f0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
10700 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
10710 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
10720 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
10730 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
10740 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
10750 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
10760 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
10770 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
10780 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
10790 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
107a0 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
107b0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
107c0 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
107d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
107e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
107f0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
10800 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
10810 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
10820 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
10830 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
10840 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
10850 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
10860 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
10870 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
10880 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
10890 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
108a0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
108b0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
108c0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
108d0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
108e0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
108f0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
10900 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
10910 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
10920 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
10930 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
10940 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
10950 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
10960 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
10970 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
10980 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
10990 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
109a0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
109b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
109c0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
109d0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
109e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
109f0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
10a00 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
10a10 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
10a20 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
10a30 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
10a40 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
10a50 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
10a60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10a70 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
10a80 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
10a90 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
10aa0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
10ab0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
10ac0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10ad0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
10ae0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10af0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20  G_MULTITHREAD]] 
10b00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10b10 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
10b20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10b30 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10b40 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10b50 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
10b60 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
10b70 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d  ading mode] to M
10b80 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e  ulti-thread.  In
10b90 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
10ba0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
10bb0 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
10bc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
10bd0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
10be0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
10bf0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
10c00 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
10c10 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
10c20 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
10c30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10c40 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
10c50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
10c60 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
10c70 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
10c80 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
10c90 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
10ca0 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
10cb0 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
10cc0 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
10cd0 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
10ce0 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
10cf0 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
10d00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10d10 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
10d20 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69   time.  ^If SQLi
10d30 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10d40 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10d50 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10d60 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10d70 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10d80 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10d90 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
10da0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d  ble to set the M
10db0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
10dc0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
10dd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10de0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
10df0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
10e00 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
10e10 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
10e20 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
10e30 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
10e40 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
10e50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10e60 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20  IG_SERIALIZED]] 
10e70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10e80 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
10e90 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
10ea0 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
10eb0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
10ec0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
10ed0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
10ee0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
10ef0 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
10f00 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
10f10 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
10f20 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
10f30 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
10f40 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
10f50 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
10f60 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
10f70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
10f80 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
10f90 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
10fa0 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
10fb0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
10fc0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
10fd0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
10fe0 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
10ff0 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
11000 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
11010 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
11020 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11030 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
11040 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
11050 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
11060 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
11070 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
11080 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
11090 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
110a0 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
110b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
110c0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
110d0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
110e0 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
110f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11100 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11110 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11120 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11130 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11140 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
11150 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11160 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
11170 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
11180 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
11190 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
111a0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
111b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
111c0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
111d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
111e0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
111f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11200 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
11210 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11220 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
11230 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
11240 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11250 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11260 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
11270 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
11280 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
11290 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
112a0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
112b0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
112c0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
112d0 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
112e0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
112f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11300 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
11310 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
11320 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
11330 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11340 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
11350 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
11360 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
11370 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
11380 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
11390 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
113a0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
113b0 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
113c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
113d0 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
113e0 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
113f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11400 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
11410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11420 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
11430 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
11440 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
11450 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
11460 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
11470 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
11480 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
11490 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
114a0 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
114b0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
114c0 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
114d0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
114e0 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
114f0 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
11500 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
11510 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
11520 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
11530 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
11540 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
11550 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
11560 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
11570 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
11580 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
11590 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
115a0 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
115b0 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
115c0 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
115d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
115e0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64  G_MEMSTATUS]] <d
115f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11600 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
11610 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
11620 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
11630 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
11640 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
11650 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
11660 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
11670 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
11680 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
11690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
116a0 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
116b0 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
116c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
116d0 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
116e0 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c  led, the .** fol
116f0 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
11700 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
11710 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
11720 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
11730 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
11740 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
11750 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
11760 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
11770 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
11780 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
11790 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
117a0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
117b0 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
117c0 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
117d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
117e0 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
117f0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
11800 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
11810 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
11820 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
11830 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
11840 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
11850 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
11860 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
11870 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
11880 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
11890 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
118a0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
118b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
118c0 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
118d0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
118e0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
118f0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
11900 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
11910 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
11920 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
11930 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
11940 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
11950 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
11960 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
11970 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
11980 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
11990 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
119a0 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
119b0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
119c0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
119d0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
119e0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
119f0 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
11a00 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
11a10 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
11a20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
11a30 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65  le of 16..** The
11a40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11a50 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
11a60 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
11a70 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
11a80 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
11a90 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
11aa0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
11ab0 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
11ac0 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20  han two scratch 
11ad0 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
11ae0 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f  ad.  So.** N sho
11af0 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77  uld be set to tw
11b00 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64  ice the expected
11b10 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
11b20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e  of threads..** ^
11b30 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11b40 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
11b50 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
11b60 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
11b70 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
11b80 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20  base page size. 
11b90 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
11ba0 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
11bb0 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
11bc0 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
11bd0 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
11be0 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
11bf0 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
11c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
11c10 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
11c20 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
11c30 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
11c40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11c50 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
11c60 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
11c70 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
11c80 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
11c90 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
11ca0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
11cb0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
11cc0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
11cd0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
11ce0 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
11cf0 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
11d00 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
11d10 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
11d20 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
11d30 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
11d40 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
11d50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
11d60 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
11d70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
11d80 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
11d90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11da0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a  PCACHE2 option..
11db0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
11dc0 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
11dd0 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
11de0 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
11df0 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
11e00 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
11e10 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
11e20 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
11e30 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
11e40 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
11e50 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
11e60 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
11e70 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
11e80 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
11e90 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
11ea0 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
11eb0 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65   plus a little e
11ec0 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a  xtra for each.**
11ed0 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
11ee0 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20  The page header 
11ef0 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30  size is 20 to 40
11f00 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67   bytes depending
11f10 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20   on.** the host 
11f20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e  architecture.  ^
11f30 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
11f40 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
11f50 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
11f60 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69   to make sz a li
11f70 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20  ttle too large. 
11f80 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
11f90 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
11fa0 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
11fb0 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
11fc0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
11fd0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
11fe0 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
11ff0 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
12000 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
12010 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
12020 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
12030 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
12040 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
12050 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
12060 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
12070 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
12080 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
12090 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
120a0 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
120b0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
120c0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
120d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
120e0 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
120f0 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
12100 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  ce..** The point
12110 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
12120 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a  argument must.**
12130 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
12140 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
12150 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
12160 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
12170 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e  te.** will be un
12180 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
12190 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
121a0 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
121b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
121c0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
121d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
121e0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
121f0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
12200 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
12210 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
12220 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
12230 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
12240 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
12250 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
12260 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
12270 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
12280 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
12290 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
122a0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
122b0 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79  guments: An 8-by
122c0 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
122d0 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
122e0 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
122f0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
12300 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
12310 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
12320 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
12330 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
12340 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
12350 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
12360 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
12370 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
12380 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
12390 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
123a0 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
123b0 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
123c0 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
123d0 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
123e0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
123f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12400 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
12410 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
12420 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
12430 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
12440 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
12450 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  r.** [SQLITE_ENA
12460 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65  BLE_MEMSYS5] are
12470 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74   defined, then t
12480 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
12490 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
124a0 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
124b0 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
124c0 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
124d0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
124e0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
124f0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
12500 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
12510 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
12520 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
12530 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
12540 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
12550 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
12560 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
12570 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12580 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
12590 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
125a0 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
125b0 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
125c0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
125d0 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
125e0 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
125f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12600 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
12610 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
12620 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12630 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12640 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12650 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
12660 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
12670 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12680 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
12690 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
126a0 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
126b0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
126c0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
126d0 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
126e0 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
126f0 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
12700 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
12710 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
12720 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
12730 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
12740 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  * content of the
12750 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
12760 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12770 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
12780 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
12790 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
127a0 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
127b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
127c0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
127d0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
127e0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
127f0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12800 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
12810 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
12820 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
12830 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
12840 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
12850 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
12860 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12870 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
12880 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
12890 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
128a0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
128b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
128c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
128d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
128e0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
128f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
12900 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12910 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12920 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12930 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
12940 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
12950 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12960 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
12970 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12980 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
12990 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
129a0 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
129b0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
129c0 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
129d0 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
129e0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
129f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12a00 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
12a10 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
12a20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
12a30 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
12a40 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
12a50 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
12a60 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
12a70 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
12a80 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
12a90 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
12aa0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12ab0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12ac0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
12ad0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12ae0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12af0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12b00 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
12b10 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
12b20 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
12b30 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
12b40 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
12b50 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12b60 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
12b70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
12b80 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
12b90 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
12ba0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
12bb0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
12bc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12bd0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
12be0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
12bf0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
12c00 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
12c10 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
12c20 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
12c30 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75  ermine the defau
12c40 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt.** memory all
12c50 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  ocation for the 
12c60 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
12c70 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61   allocator on ea
12c80 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
12c90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
12ca0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12cb0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
12cc0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
12cd0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
12ce0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
12cf0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
12d00 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
12d10 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
12d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
12d30 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73   ^(This option s
12d40 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
12d50 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
12d60 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
12d70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
12d80 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72  OOKASIDE].** ver
12d90 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  b to [sqlite3_db
12da0 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
12db0 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
12dc0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
12dd0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
12de0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
12df0 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
12e00 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12e10 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
12e20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12e30 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
12e40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12e50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12e60 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12e70 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12e80 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c  er to.** an [sql
12e90 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
12ea0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
12eb0 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
12ec0 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
12ed0 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
12ee0 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
12ef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20  lementation.)^  
12f00 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
12f10 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
12f20 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69  bject and uses i
12f30 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  t for page cache
12f40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12f50 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ons.</dd>.**.** 
12f60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12f70 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
12f80 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12f90 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
12fa0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
12fb0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12fc0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12fd0 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12fe0 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
12ff0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
13000 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
13010 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
13020 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
13030 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13040 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
13050 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
13060 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13070 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
13080 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13090 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  G</dt>.** <dd> ^
130a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
130b0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
130c0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
130d0 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
130e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
130f0 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
13100 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
13110 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
13120 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
13130 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
13140 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
13150 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
13160 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
13170 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
13180 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
13190 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
131a0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
131b0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
131c0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
131d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
131e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
131f0 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
13200 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
13210 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
13220 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
13230 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
13240 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
13250 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
13260 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13270 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
13280 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
13290 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
132a0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
132b0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
132c0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
132d0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
132e0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
132f0 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
13300 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
13310 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
13320 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
13330 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
13340 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
13350 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
13360 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
13370 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
13380 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
13390 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
133a0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
133b0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
133c0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
133d0 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
133e0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
133f0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
13400 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
13410 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
13420 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
13430 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
13440 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
13450 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
13460 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
13470 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
13480 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
13490 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
134a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
134b0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
134c0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
134d0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
134e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
134f0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
13500 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13510 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68  G_URI.** <dd> Th
13520 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13530 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13540 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49  t of type int. I
13550 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
13560 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  .** URI handling
13570 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
13580 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
13590 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20  ameter is zero, 
135a0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
135b0 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79  g.** is globally
135c0 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52   disabled. If UR
135d0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
135e0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
135f0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
13600 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
13610 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
13620 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
13630 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
13640 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
13650 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
13660 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
13670 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
13680 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
13690 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
136a0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
136b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
136c0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
136d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
136e0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
136f0 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73  opened. If it is
13700 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
13710 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
13720 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
13730 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
13740 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
13750 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
13760 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
13770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13780 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64   is opened. By d
13790 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
137a0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
137b0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
137c0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
137d0 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
137e0 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
137f0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
13800 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
13810 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b  defined..**.** [
13820 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
13830 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
13840 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
13850 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
13860 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
13870 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
13880 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
13890 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77  teger argument w
138a0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
138b0 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c  ted as.** a bool
138c0 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
138d0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
138e0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
138f0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
13900 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20  r.** full table 
13910 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
13920 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54  ry optimizer.  T
13930 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
13940 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
13950 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
13960 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
13970 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
13980 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13990 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
139a0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
139b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
139c0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
139d0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
139e0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
139f0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
13a00 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
13a10 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
13a20 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
13a30 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
13a40 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
13a50 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
13a60 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68  * malfunction wh
13a70 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
13a80 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
13a90 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
13aa0 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
13ab0 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
13ac0 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
13ad0 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
13ae0 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
13af0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
13b00 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
13b10 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
13b20 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
13b30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13b40 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
13b50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
13b60 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
13b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13b80 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
13b90 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
13ba0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
13bb0 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
13bc0 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
13bd0 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
13be0 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
13bf0 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
13c00 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
13c10 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
13c20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
13c30 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dl>.**.** [[SQL
13c40 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
13c50 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
13c60 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
13c70 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
13c80 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
13c90 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
13ca0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
13cb0 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e  the.** SQLITE_EN
13cc0 41 42 4c 45 5f 53 51 4c 4c 4f 47 20 70 72 65 2d  ABLE_SQLLOG pre-
13cd0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
13ce0 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72  defined. The fir
13cf0 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
13d00 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74  ld.** be a point
13d10 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  er to a function
13d20 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29   of type void(*)
13d30 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
13d40 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
13d50 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
13d60 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79   should be of ty
13d70 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20  pe (void*). The 
13d80 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
13d90 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61  ked by the libra
13da0 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73  ry.** in three s
13db0 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74  eparate circumst
13dc0 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65  ances, identifie
13dd0 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70  d by the value p
13de0 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
13df0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
13e00 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  . If the fourth 
13e10 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20  parameter is 0, 
13e20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
13e30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
13e40 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
13e50 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61  cond argument ha
13e60 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e  s just been open
13e70 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  ed. The third ar
13e80 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73  gument.** points
13e90 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e   to a buffer con
13ea0 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65  taining the name
13eb0 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74   of the main dat
13ec0 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74  abase file. If t
13ed0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
13ee0 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65  ameter is 1, the
13ef0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
13f00 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69  ent that the thi
13f10 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
13f20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75  points to has ju
13f30 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64  st been executed
13f40 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75  . Or, if the fou
13f50 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
13f60 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   2, then.** the 
13f70 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67  connection being
13f80 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
13f90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13fa0 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e  is being closed.
13fb0 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   The.** third pa
13fc0 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65  rameter is passe
13fd0 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63  d NULL In this c
13fe0 61 73 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ase..** </dl>.*/
13ff0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14000 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
14010 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
14020 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14030 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
14040 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
14050 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14060 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
14070 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
14080 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14090 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
140a0 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
140b0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
140c0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
140d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
140e0 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
140f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14100 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14120 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
14130 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
14140 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
14150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14160 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
14170 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
14180 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
14190 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
141a0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
141b0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
141c0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
141d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
141e0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
141f0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
14200 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
14210 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14220 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
14230 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
14240 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
14250 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14260 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
14270 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
14280 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
14290 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
142a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
142b0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
142c0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
142d0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
142e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
142f0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
14300 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14310 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14320 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
14330 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
14340 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14350 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
14360 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
14370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14380 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
14390 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
143a0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
143b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
143c0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
143d0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
143e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
143f0 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
14400 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
14410 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
14420 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14430 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
14440 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
14450 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14460 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14470 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14480 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
14490 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
144a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
144b0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
144c0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
144d0 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  void* */../*.** 
144e0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
144f0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
14500 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
14510 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
14520 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
14530 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
14540 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
14550 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
14560 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
14570 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
14580 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
14590 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
145a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
145b0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
145c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
145d0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
145e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
145f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
14600 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
14610 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
14620 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
14630 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
14640 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
14650 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
14660 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
14670 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
14680 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
14690 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
146a0 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
146b0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
146c0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
146d0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
146e0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
146f0 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
14700 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
14710 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14720 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
14730 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
14740 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
14750 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
14760 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14770 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
14780 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
14790 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
147a0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
147b0 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
147c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
147d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
147e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
147f0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
14800 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14810 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
14820 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
14830 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
14840 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
14850 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
14860 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
14870 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
14880 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
14890 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
148a0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
148b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
148c0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
148d0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
148e0 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
148f0 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
14900 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
14910 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
14920 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
14930 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14940 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
14950 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
14960 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
14970 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
14980 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
14990 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
149a0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
149b0 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
149c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
149d0 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
149e0 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
149f0 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
14a00 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
14a10 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
14a20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
14a30 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
14a40 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
14a50 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
14a60 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
14a70 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
14a80 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
14a90 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
14aa0 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
14ab0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
14ac0 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
14ad0 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
14ae0 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
14af0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
14b00 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
14b10 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
14b20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
14b30 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
14b40 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
14b50 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
14b60 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
14b70 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
14b80 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
14b90 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
14ba0 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
14bb0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
14bc0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
14bd0 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
14be0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
14bf0 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
14c00 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
14c10 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
14c20 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
14c30 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
14c40 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
14c50 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
14c60 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
14c70 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
14c80 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
14c90 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
14ca0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
14cb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14cc0 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
14cd0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
14ce0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
14cf0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
14d00 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
14d10 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
14d20 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
14d30 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
14d40 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
14d50 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
14d60 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
14d70 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
14d80 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
14d90 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
14da0 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
14db0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
14dc0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
14dd0 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
14de0 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
14df0 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
14e00 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
14e10 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
14e20 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
14e30 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
14e40 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
14e50 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
14e60 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
14e70 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
14e80 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
14e90 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
14ea0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
14eb0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
14ec0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
14ed0 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
14ee0 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
14ef0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
14f00 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
14f10 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
14f20 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
14f30 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
14f40 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
14f50 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
14f60 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
14f70 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
14f80 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
14f90 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
14fa0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
14fb0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
14fc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
14fd0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
14fe0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
14ff0 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
15000 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
15010 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
15020 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
15030 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
15040 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
15050 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15060 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15070 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
15080 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
15090 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
150a0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
150b0 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
150c0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
150d0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
150e0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
150f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
15100 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
15110 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
15120 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
15130 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
15140 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
15150 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
15160 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
15170 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15180 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
15190 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
151a0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
151b0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
151c0 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
151d0 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
151e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
151f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
15200 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
15210 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
15220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15230 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
15240 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
15250 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
15260 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
15270 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
15280 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
15290 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
152a0 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
152b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
152c0 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
152d0 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
152e0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
152f0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
15300 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
15310 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
15320 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ility..*/.SQLITE
15330 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
15340 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
15350 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
15360 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
15370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
15380 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
15390 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
153a0 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
153b0 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
153c0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
153d0 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
153e0 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
153f0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
15400 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
15410 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
15420 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
15430 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
15440 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
15450 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
15460 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
15470 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
15480 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
15490 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
154a0 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
154b0 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
154c0 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
154d0 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
154e0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
154f0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
15500 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
15510 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
15520 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
15530 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d  [rowid] of the m
15540 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
15550 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
15560 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
15570 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
15580 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15590 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
155a0 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41  st argument.  ^A
155b0 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
155c0 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20  ion 3.7.7, this 
155d0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f  routines.** reco
155e0 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  rds the last ins
155f0 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74  ert rowid of bot
15600 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65  h ordinary table
15610 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74  s and [virtual t
15620 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e  ables]..** ^If n
15630 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
15640 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
15650 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
15660 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
15670 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
15680 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
15690 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
156a0 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
156b0 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
156c0 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
156d0 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
156e0 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
156f0 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
15700 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
15710 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
15720 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
15730 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
15740 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
15750 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
15760 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
15770 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
15780 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
15790 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
157a0 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
157b0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
157c0 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
157d0 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
157e0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
157f0 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
15800 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
15810 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
15820 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
15830 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
15840 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
15850 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
15860 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
15870 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
15880 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
15890 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
158a0 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
158b0 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
158c0 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
158d0 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
158e0 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
158f0 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
15900 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
15910 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
15920 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
15930 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
15940 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
15950 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
15960 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
15970 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
15980 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
15990 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
159a0 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
159b0 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
159c0 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
159d0 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
159e0 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
159f0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
15a00 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
15a10 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
15a20 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
15a30 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
15a40 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
15a50 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
15a60 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
15a70 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
15a80 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
15a90 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
15aa0 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
15ab0 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
15ac0 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
15ad0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
15ae0 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
15af0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
15b00 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
15b10 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
15b20 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
15b30 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
15b40 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
15b50 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
15b60 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
15b70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15b80 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
15b90 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
15ba0 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
15bb0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
15bc0 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
15bd0 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
15be0 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
15bf0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
15c00 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
15c10 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
15c20 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
15c30 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
15c40 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
15c50 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
15c60 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
15c70 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
15c80 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
15c90 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
15ca0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
15cb0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
15cc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15cd0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
15ce0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
15cf0 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
15d00 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
15d10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
15d20 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
15d30 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
15d40 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
15d50 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
15d60 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
15d70 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
15d80 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
15d90 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
15da0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
15db0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
15dc0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f  arameter..** ^(O
15dd0 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
15de0 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
15df0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b  ecified by the [
15e00 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
15e10 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45  ],.** or [DELETE
15e20 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  ] statement are 
15e30 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
15e40 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
15e50 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
15e60 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65  s or [foreign ke
15e70 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e  y actions] are n
15e80 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73  ot counted.)^ Us
15e90 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
15ea0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
15eb0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66  )] function to f
15ec0 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
15ed0 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a  mber of changes.
15ee0 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  ** including cha
15ef0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
15f00 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65  riggers and fore
15f10 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e  ign key actions.
15f20 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  .**.** ^Changes 
15f30 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
15f40 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20  re simulated by 
15f50 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
15f60 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e  rigger].** are n
15f70 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c  ot counted.  Onl
15f80 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61  y real table cha
15f90 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
15fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77  ..**.** ^(A "row
15fb0 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
15fc0 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
15fd0 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
15fe0 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
15ff0 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
16000 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
16010 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
16020 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
16030 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
16040 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43  fects of [REPLAC
16050 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
16060 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
16070 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
16080 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54  cessing, [DROP T
16090 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79  ABLE], or by any
160a0 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
160b0 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
160c0 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
160d0 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  changes.)^.**.**
160e0 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
160f0 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
16100 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
16110 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
16120 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
16130 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54  ript of a [CREAT
16140 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
16150 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53  ger]. .** Most S
16160 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
16170 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
16180 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
16190 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
161a0 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
161b0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
161c0 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
161d0 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
161e0 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
161f0 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
16200 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
16210 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
16220 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
16230 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
16240 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
16250 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
16260 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
16270 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  ** ^Calling [sql
16280 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
16290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
162a0 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
162b0 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
162c0 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
162d0 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
162e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
162f0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16300 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
16310 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
16320 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
16330 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
16340 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
16350 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
16360 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
16370 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20  t..**.** ^Thus, 
16380 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
16390 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
163a0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
163b0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
163c0 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
163d0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
163e0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
163f0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
16400 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
16410 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
16420 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68  el.  ^(Within th
16430 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
16440 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
16450 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
16460 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
16470 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
16480 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
16490 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
164a0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
164b0 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
164c0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
164d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
164e0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
164f0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
16500 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
16510 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
16520 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
16530 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
16540 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
16550 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
16560 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
16570 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ontext.)^.**.** 
16580 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
16590 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
165a0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
165b0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
165c0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
165d0 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
165e0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
165f0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
16600 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
16610 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
16620 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
16630 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
16640 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
16650 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
16660 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
16670 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
16680 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
16690 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
166a0 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
166b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  I int sqlite3_ch
166c0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
166d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
166e0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
166f0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
16700 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
16710 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
16720 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
16730 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
16740 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
16750 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
16760 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
16770 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
16780 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
16790 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
167a0 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
167b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
167c0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
167d0 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
167e0 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
167f0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
16800 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
16810 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
16820 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
16830 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
16840 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
16850 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
16860 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
16870 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
16880 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
16890 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
168a0 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
168b0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
168c0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
168d0 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
168e0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
168f0 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
16900 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
16910 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
16920 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
16930 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
16940 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
16950 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
16960 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
16970 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
16980 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
16990 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
169a0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
169b0 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
169c0 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
169d0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
169e0 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
169f0 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
16a00 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
16a10 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
16a20 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
16a30 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
16a40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
16a50 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
16a60 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
16a70 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
16a80 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
16a90 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
16aa0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
16ab0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
16ac0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
16ad0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
16ae0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
16af0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
16b00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
16b10 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
16b20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
16b30 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
16b40 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
16b50 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
16b60 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
16b70 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
16b80 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
16b90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  I int sqlite3_to
16ba0 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
16bb0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
16bc0 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
16bd0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
16be0 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
16bf0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
16c00 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
16c10 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
16c20 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
16c30 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
16c40 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
16c50 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
16c60 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
16c70 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
16c80 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
16c90 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
16ca0 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
16cb0 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
16cc0 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
16cd0 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
16ce0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
16cf0 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
16d00 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
16d10 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
16d20 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
16d30 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
16d40 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
16d50 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
16d60 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
16d70 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
16d80 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
16d90 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
16da0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
16db0 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
16dc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
16dd0 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
16de0 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
16df0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
16e00 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
16e10 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
16e20 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
16e30 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
16e40 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
16e50 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
16e60 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
16e70 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
16e80 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
16e90 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
16ea0 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
16eb0 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
16ec0 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
16ed0 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
16ee0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
16ef0 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
16f00 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
16f10 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
16f20 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
16f30 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
16f40 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
16f50 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
16f60 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
16f70 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
16f80 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
16f90 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
16fa0 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
16fb0 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
16fc0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
16fd0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
16fe0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16ff0 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
17000 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
17010 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
17020 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
17030 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
17040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
17050 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
17060 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
17070 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
17080 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
17090 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
170a0 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
170b0 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
170c0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
170d0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
170e0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
170f0 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
17100 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
17110 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
17120 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
17130 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
17140 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
17150 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
17160 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
17170 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
17180 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
17190 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
171a0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
171b0 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
171c0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
171d0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
171e0 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
171f0 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
17200 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
17210 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
17220 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
17230 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
17240 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
17250 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
17260 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17270 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
17280 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
17290 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
172a0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
172b0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
172c0 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
172d0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
172e0 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
172f0 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51  ly happen..*/.SQ
17300 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
17310 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17320 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17330 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
17340 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
17350 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
17360 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
17370 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
17380 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
17390 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
173a0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
173b0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
173c0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
173d0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
173e0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
173f0 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
17400 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
17410 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
17420 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
17430 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
17440 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
17450 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
17460 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
17470 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
17480 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
17490 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
174a0 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
174b0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
174c0 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
174d0 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
174e0 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
174f0 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
17500 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
17510 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
17520 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
17530 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
17540 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
17550 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
17560 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
17570 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
17580 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
17590 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
175a0 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
175b0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
175c0 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
175d0 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
175e0 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
175f0 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
17600 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
17610 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
17620 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
17630 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
17640 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
17650 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
17660 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
17670 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
17680 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
17690 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
176a0 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
176b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
176c0 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
176d0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
176e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
176f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
17700 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
17710 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
17720 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
17730 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
17740 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
17750 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
17760 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
17770 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
17780 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
17790 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
177a0 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
177b0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
177c0 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
177d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
177e0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
177f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
17800 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
17810 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
17820 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
17830 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
17840 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
17850 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
17860 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
17870 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
17880 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
17890 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
178a0 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
178b0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
178c0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
178d0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
178e0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
178f0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
17900 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
17910 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
17920 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
17930 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
17940 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
17950 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
17960 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
17970 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
17980 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
17990 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
179a0 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f  r *sql);.SQLITE_
179b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
179c0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
179d0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
179e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
179f0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
17a00 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
17a10 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
17a20 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
17a30 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
17a40 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
17a50 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
17a60 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
17a70 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
17a80 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
17a90 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
17aa0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
17ab0 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
17ac0 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
17ad0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
17ae0 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
17af0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
17b00 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
17b10 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
17b20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
17b30 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
17b40 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
17b50 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
17b60 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
17b70 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
17b80 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
17b90 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
17ba0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
17bb0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
17bc0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
17bd0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
17be0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
17bf0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
17c00 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
17c10 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
17c20 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
17c30 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
17c40 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
17c50 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
17c60 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
17c70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
17c80 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
17c90 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
17ca0 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
17cb0 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
17cc0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
17cd0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
17ce0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
17cf0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
17d00 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
17d10 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
17d20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
17d30 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
17d40 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
17d50 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
17d60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
17d70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
17d80 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
17d90 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
17da0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
17db0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
17dc0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
17dd0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
17de0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
17df0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
17e00 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
17e10 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
17e20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
17e30 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
17e40 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
17e50 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
17e60 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
17e70 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
17e80 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
17e90 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
17ea0 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
17eb0 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
17ec0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
17ed0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
17ee0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
17ef0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
17f00 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
17f10 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
17f20 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
17f30 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
17f40 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
17f50 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
17f60 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
17f70 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
17f80 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
17f90 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
17fa0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
17fb0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
17fc0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
17fd0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
17fe0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
17ff0 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
18000 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
18010 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
18020 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
18030 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
18040 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
18050 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
18060 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
18070 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
18080 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
18090 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
180a0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
180b0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
180c0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
180d0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
180e0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
180f0 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
18100 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
18110 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
18120 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
18130 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
18140 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
18150 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
18160 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
18170 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
18180 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
18190 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
181a0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
181b0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
181c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
181d0 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
181e0 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
181f0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
18200 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
18210 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
18220 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
18230 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
18240 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
18250 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
18260 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
18270 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
18280 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
18290 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
182a0 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
182b0 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
182c0 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
182d0 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
182e0 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
182f0 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
18300 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
18310 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
18320 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
18330 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
18340 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
18350 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
18360 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
18370 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
18380 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
18390 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
183a0 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
183b0 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
183c0 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
183d0 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
183e0 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
183f0 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
18400 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
18410 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
18420 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
18430 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
18440 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
18450 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
18460 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
18470 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
18480 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
18490 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
184a0 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
184b0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
184c0 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
184d0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
184e0 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
184f0 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
18500 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
18510 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
18520 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
18530 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
18540 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
18550 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
18560 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
18570 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
18580 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
18590 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
185a0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
185b0 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
185c0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
185d0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
185e0 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
185f0 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
18600 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
18610 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
18620 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
18630 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
18640 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
18650 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
18660 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18670 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
18680 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
18690 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
186a0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
186b0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
186c0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
186d0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
186e0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
186f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18700 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
18710 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
18720 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
18730 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51  y handler..*/.SQ
18740 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
18750 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
18760 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
18770 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
18780 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
18790 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
187a0 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
187b0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
187c0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
187d0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
187e0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
187f0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
18800 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
18810 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
18820 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
18830 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
18840 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
18850 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
18860 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
18870 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
18880 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
18890 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
188a0 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
188b0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
188c0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
188d0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
188e0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
188f0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
18900 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
18910 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
18920 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
18930 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
18940 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
18950 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
18960 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
18970 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
18980 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
18990 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
189a0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
189b0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
189c0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
189d0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
189e0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
189f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
18a00 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
18a10 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
18a20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
18a30 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
18a40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
18a50 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
18a60 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
18a70 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
18a80 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
18a90 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
18aa0 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ed.)^.*/.SQLITE_
18ab0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
18ac0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
18ad0 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
18ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18af0 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
18b00 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
18b10 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
18b20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
18b30 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
18b40 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
18b50 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
18b60 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
18b70 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
18b80 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
18b90 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
18ba0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
18bb0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
18bc0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
18bd0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
18be0 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
18bf0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
18c00 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
18c10 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
18c20 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
18c30 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
18c40 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
18c50 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
18c60 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
18c70 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
18c80 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
18c90 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
18ca0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
18cb0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
18cc0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
18cd0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
18ce0 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
18cf0 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
18d00 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
18d10 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
18d20 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
18d30 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
18d40 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
18d50 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
18d60 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
18d70 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
18d80 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
18d90 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
18da0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
18db0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
18dc0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
18dd0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
18de0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18df0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
18e00 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
18e10 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
18e20 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
18e30 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
18e40 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
18e50 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
18e60 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
18e70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
18e80 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
18e90 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
18ea0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
18eb0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
18ec0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
18ed0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
18ee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
18ef0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
18f00 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
18f10 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
18f20 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
18f30 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
18f40 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
18f50 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
18f60 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
18f70 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
18f80 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
18f90 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
18fa0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
18fb0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
18fc0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
18fd0 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
18fe0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
18ff0 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
19000 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
19010 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
19020 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
19030 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
19040 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
19050 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
19060 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
19070 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
19080 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
19090 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
190a0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
190b0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
190c0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
190d0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
190e0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
190f0 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
19100 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
19110 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
19120 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
19130 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
19140 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
19150 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
19160 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
19170 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
19180 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
19190 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
191a0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
191b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
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 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
191e0 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
191f0 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
19200 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
19210 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
19220 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
19230 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19240 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
19250 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19260 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
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 35 5d 20 3d 20 22 32  sult&#91;5] = "2
19290 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
192a0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
192b0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
192c0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
192d0 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
192e0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
192f0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
19300 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19310 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
19320 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
19330 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
19340 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
19350 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
19360 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
19370 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
19380 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
19390 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
193a0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
193b0 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
193c0 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
193d0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
193e0 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
193f0 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
19400 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
19410 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
19420 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
19430 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
19440 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
19450 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
19460 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
19470 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
19480 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
19490 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
194a0 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
194b0 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
194c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
194d0 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
194e0 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
194f0 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
19500 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
19510 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
19520 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
19530 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
19540 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
19550 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
19560 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
19570 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
19580 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
19590 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
195a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
195b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
195c0 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
195d0 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
195e0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
195f0 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
19600 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
19610 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
19620 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
19630 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
19640 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
19650 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
19660 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
19670 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
19680 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
19690 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
196a0 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
196b0 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
196c0 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
196d0 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
196e0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
196f0 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
19700 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
19710 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
19720 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
19730 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
19740 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
19750 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
19760 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
19770 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
19780 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
19790 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
197a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
197b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
197c0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
197d0 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
197e0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
197f0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
19800 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
19810 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
19820 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
19830 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
19840 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
19850 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
19860 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
19870 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
19880 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
19890 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
198a0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
198b0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
198c0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
198d0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72   void sqlite3_fr
198e0 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
198f0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
19900 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
19910 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
19920 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
19930 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
19940 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
19950 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
19960 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
19970 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
19980 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
19990 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
199a0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
199b0 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
199c0 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
199d0 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
199e0 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
199f0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
19a00 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
19a10 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
19a20 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
19a30 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
19a40 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
19a50 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
19a60 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
19a70 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
19a80 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
19a90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
19aa0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
19ab0 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
19ac0 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
19ad0 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
19ae0 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
19af0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
19b00 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
19b10 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
19b20 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
19b30 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
19b40 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
19b50 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
19b60 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
19b70 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
19b80 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
19b90 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
19ba0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
19bb0 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
19bc0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19bd0 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
19be0 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
19bf0 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
19c00 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
19c10 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
19c20 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
19c30 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
19c40 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
19c50 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
19c60 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
19c70 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
19c80 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
19c90 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
19ca0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
19cb0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
19cc0 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
19cd0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
19ce0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
19cf0 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
19d00 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
19d10 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
19d20 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
19d30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
19d40 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
19d50 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
19d60 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
19d70 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
19d80 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
19d90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
19da0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
19db0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
19dc0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
19dd0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
19de0 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
19df0 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
19e00 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
19e10 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
19e20 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
19e30 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
19e40 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
19e50 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
19e60 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
19e70 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
19e80 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
19e90 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
19ea0 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
19eb0 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
19ec0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
19ed0 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
19ee0 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
19ef0 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
19f00 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
19f10 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
19f20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
19f30 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
19f40 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
19f50 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
19f60 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
19f70 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
19f80 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
19f90 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
19fa0 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
19fb0 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
19fc0 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
19fd0 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
19fe0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
19ff0 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1a000 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1a010 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1a020 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1a030 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1a040 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
1a050 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1a060 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1a070 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1a080 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1a090 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1a0a0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1a0b0 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1a0c0 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1a0d0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1a0e0 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1a0f0 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1a100 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1a110 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1a120 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1a130 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1a140 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1a150 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1a160 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1a170 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1a180 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1a190 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1a1a0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1a1b0 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1a1c0 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1a1d0 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1a1e0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1a1f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a200 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1a210 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1a220 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1a230 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1a240 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1a250 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1a260 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1a270 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1a280 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1a290 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1a2a0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1a2b0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1a2c0 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1a2d0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1a2e0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1a2f0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1a300 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1a310 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1a320 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1a330 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1a340 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1a350 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1a360 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1a370 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1a380 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1a390 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1a3a0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1a3b0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1a3c0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1a3d0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1a3e0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1a3f0 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1a400 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1a410 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1a420 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1a430 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1a440 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1a450 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1a460 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1a470 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1a480 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1a490 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1a4a0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1a4b0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1a4c0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1a4d0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1a4e0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1a4f0 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1a500 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1a510 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1a520 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1a530 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1a540 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1a550 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1a560 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1a570 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1a580 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1a590 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1a5a0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1a5b0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1a5c0 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1a5d0 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1a5e0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1a5f0 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1a600 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1a610 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1a620 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1a630 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1a640 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1a650 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1a660 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1a670 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1a680 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1a690 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1a6a0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1a6b0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1a6c0 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1a6d0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1a6e0 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1a6f0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1a700 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1a710 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1a720 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1a730 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a740 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1a750 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1a760 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1a770 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1a780 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1a790 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1a7a0 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1a7b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1a7c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1a7d0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1a7e0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1a7f0 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1a800 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1a810 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1a820 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1a830 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1a840 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1a850 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1a860 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1a870 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1a880 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
1a890 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
1a8a0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1a8b0 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41  *,...);.SQLITE_A
1a8c0 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
1a8d0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1a8e0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1a8f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1a900 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1a910 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1a920 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1a930 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1a940 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e  *sqlite3_vsnprin
1a950 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1a960 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1a970 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1a980 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1a990 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
1a9a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
1a9b0 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
1a9c0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
1a9d0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
1a9e0 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
1a9f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1aa00 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
1aa10 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1aa20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
1aa30 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
1aa40 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
1aa50 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
1aa60 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
1aa70 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
1aa80 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
1aa90 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
1aaa0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
1aab0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1aac0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1aad0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1aae0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
1aaf0 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
1ab00 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
1ab10 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
1ab20 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
1ab30 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
1ab40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ab50 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
1ab60 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
1ab70 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
1ab80 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
1ab90 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
1aba0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
1abb0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
1abc0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1abd0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
1abe0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1abf0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
1ac00 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1ac10 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
1ac20 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
1ac30 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
1ac40 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
1ac50 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1ac60 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1ac70 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
1ac80 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
1ac90 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
1aca0 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
1acb0 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
1acc0 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
1acd0 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
1ace0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1acf0 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
1ad00 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
1ad10 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
1ad20 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
1ad30 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
1ad40 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
1ad50 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
1ad60 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
1ad70 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
1ad80 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
1ad90 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
1ada0 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
1adb0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1adc0 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
1add0 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
1ade0 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
1adf0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1ae00 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
1ae10 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
1ae20 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
1ae30 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1ae40 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
1ae50 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
1ae60 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
1ae70 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1ae80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1ae90 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1aea0 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  c()..**.** ^(The
1aeb0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1aec0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
1aed0 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
1aee0 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
1aef0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1af00 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1af10 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
1af20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
1af30 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
1af40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1af50 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
1af60 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
1af70 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20  rameter.)^ ^ If 
1af80 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1af90 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1afa0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1afb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1afc0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1afd0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1afe0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1aff0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65  e3_malloc(N) whe
1b000 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
1b010 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1b020 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b030 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65  )..** ^If the se
1b040 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1b050 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1b060 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
1b070 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
1b080 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1b090 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
1b0a0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
1b0b0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
1b0c0 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
1b0d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1b0e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b0f0 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ()..** ^sqlite3_
1b100 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
1b110 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1b120 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b130 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1b140 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1b150 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
1b160 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1b170 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
1b180 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1b190 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1b1a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1b1b0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1b1c0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1b1d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1b1e0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1b1f0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1b200 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1b210 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1b220 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
1b230 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1b240 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
1b250 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b260 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
1b270 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
1b280 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
1b290 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1b2a0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
1b2b0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1b2c0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
1b2d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
1b2e0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1b2f0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1b300 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1b310 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1b320 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1b330 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1b340 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1b350 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1b360 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1b370 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1b380 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1b390 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1b3a0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1b3b0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1b3c0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1b3d0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1b3e0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1b3f0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1b400 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1b410 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1b420 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1b430 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1b440 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1b450 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1b460 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1b470 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1b480 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1b490 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1b4a0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1b4b0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1b4c0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1b4d0 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1b4e0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1b4f0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1b500 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1b510 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1b520 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1b530 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1b540 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1b550 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1b560 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1b570 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1b580 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1b590 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1b5a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1b5b0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1b5c0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1b5d0 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1b5e0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1b5f0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1b600 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1b610 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1b620 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1b630 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1b640 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1b650 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1b660 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1b670 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1b680 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1b690 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1b6a0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1b6b0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1b6c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1b6d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1b6e0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1b6f0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1b700 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1b710 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1b720 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1b730 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1b740 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1b750 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1b760 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1b770 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1b780 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1b790 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1b7a0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  lloc()]..*/.SQLI
1b7b0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1b7c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1b7d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1b7e0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1b7f0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1b800 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1b810 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1b820 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1b830 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1b840 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
1b850 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
1b860 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
1b870 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
1b880 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
1b890 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
1b8a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
1b8b0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
1b8c0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
1b8d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1b8e0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
1b8f0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
1b900 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1b910 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
1b920 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
1b930 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1b940 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
1b950 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1b960 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
1b970 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
1b980 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
1b990 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
1b9a0 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
1b9b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1b9c0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
1b9d0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1b9e0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
1b9f0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
1ba00 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
1ba10 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
1ba20 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
1ba30 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
1ba40 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1ba50 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1ba60 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
1ba70 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1ba80 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
1ba90 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
1baa0 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
1bab0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
1bac0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1bad0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1bae0 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
1baf0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
1bb00 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
1bb10 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
1bb20 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
1bb30 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
1bb40 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
1bb50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1bb60 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
1bb70 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
1bb80 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
1bb90 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
1bba0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
1bbb0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
1bbc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1bbd0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1bbe0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
1bbf0 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
1bc00 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
1bc10 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1bc20 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
1bc30 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
1bc40 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
1bc50 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
1bc60 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
1bc70 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1bc80 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
1bc90 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
1bca0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1bcb0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1bcc0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1bcd0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1bce0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1bcf0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1bd00 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1bd10 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1bd20 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1bd30 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1bd40 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1bd50 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1bd60 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1bd70 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1bd80 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1bd90 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1bda0 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1bdb0 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1bdc0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1bdd0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1bde0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1bdf0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1be00 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1be10 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1be20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1be30 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1be40 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1be50 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1be60 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1be70 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1be80 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1be90 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1bea0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1beb0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1bec0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
1bed0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
1bee0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
1bef0 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
1bf00 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
1bf10 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
1bf20 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
1bf30 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1bf40 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
1bf50 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
1bf60 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1bf70 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
1bf80 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1bf90 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
1bfa0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
1bfb0 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
1bfc0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1bfd0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1bfe0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1bff0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1c000 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1c010 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1c020 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49   method..*/.SQLI
1c030 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1c040 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
1c050 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
1c060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c070 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
1c080 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
1c090 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
1c0a0 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1c0b0 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1c0c0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1c0d0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1c0e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c0f0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1c100 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1c110 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1c120 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1c130 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1c140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1c150 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1c160 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1c170 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1c180 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1c190 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c1a0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1c1b0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1c1c0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1c1d0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1c1e0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1c1f0 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1c200 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1c210 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1c220 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1c230 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1c240 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1c250 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c260 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1c270 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1c280 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1c290 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1c2a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c2b0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1c2c0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1c2d0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1c2e0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1c2f0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1c300 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1c310 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1c320 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1c330 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1c340 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1c350 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1c360 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1c370 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1c380 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1c390 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1c3a0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1c3b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c3c0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1c3d0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1c3e0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1c3f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1c400 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1c410 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1c420 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c430 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1c440 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1c450 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1c460 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1c470 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1c480 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1c490 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1c4a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1c4b0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1c4c0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1c4d0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1c4e0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1c4f0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1c500 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1c510 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1c520 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1c530 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1c540 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1c550 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1c560 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1c570 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1c580 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1c590 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1c5a0 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1c5b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1c5c0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1c5d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1c5e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1c5f0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1c600 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1c610 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1c620 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1c630 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1c640 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1c650 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1c660 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1c670 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1c680 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1c690 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1c6a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1c6b0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1c6c0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1c6d0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1c6e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1c6f0 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1c700 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1c710 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1c720 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1c730 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1c740 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1c750 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
1c760 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1c770 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1c780 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1c790 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1c7a0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1c7b0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1c7c0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1c7d0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1c7e0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1c7f0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1c800 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1c810 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1c820 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1c830 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1c840 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1c850 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1c860 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1c870 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1c880 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1c890 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1c8a0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1c8b0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1c8c0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1c8d0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1c8e0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1c8f0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1c900 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1c910 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1c920 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1c930 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1c940 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1c950 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1c960 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1c970 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1c980 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1c990 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1c9a0 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1c9b0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1c9c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1c9d0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1c9e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1c9f0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1ca00 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1ca10 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1ca20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1ca30 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1ca40 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1ca50 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1ca60 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1ca70 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1ca80 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1ca90 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1caa0 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1cab0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1cac0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1cad0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1cae0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1caf0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1cb00 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1cb10 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1cb20 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1cb30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1cb40 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1cb50 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1cb60 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1cb70 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1cb80 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1cb90 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1cba0 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1cbb0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1cbc0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1cbd0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1cbe0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1cbf0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1cc00 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1cc10 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1cc20 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1cc30 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1cc40 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1cc50 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1cc60 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1cc70 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1cc80 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1cc90 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1cca0 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1ccb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1ccc0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1ccd0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1cce0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1ccf0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1cd00 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1cd10 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1cd20 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1cd30 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1cd40 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1cd50 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1cd60 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1cd70 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1cd80 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1cd90 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1cda0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1cdb0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1cdc0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1cdd0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1cde0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1cdf0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1ce00 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1ce10 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1ce20 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1ce30 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1ce40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1ce50 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1ce60 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1ce70 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1ce80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1ce90 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1cea0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ceb0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1cec0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ced0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1cee0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1cef0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1cf00 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1cf10 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1cf20 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1cf30 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1cf40 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1cf50 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1cf60 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1cf70 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1cf80 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1cf90 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1cfa0 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1cfb0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1cfc0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1cfd0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1cfe0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1cff0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1d000 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1d010 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1d020 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d030 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1d040 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1d050 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1d060 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1d070 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1d080 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1d090 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1d0a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1d0b0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1d0c0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1d0d0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1d0e0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1d0f0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1d100 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1d110 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1d120 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1d130 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1d140 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1d150 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1d160 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1d170 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1d180 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1d190 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1d1a0 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49   change..*/.SQLI
1d1b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1d1c0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1d1d0 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
1d1e0 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
1d1f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
1d200 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1d210 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1d220 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
1d230 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
1d240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d250 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
1d260 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1d270 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1d280 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1d290 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d2a0 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
1d2b0 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
1d2c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
1d2d0 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
1d2e0 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
1d2f0 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
1d300 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
1d310 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
1d320 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
1d330 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
1d340 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1d350 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1d360 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
1d370 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1d380 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1d390 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
1d3a0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61  LITE_IGNORE is a
1d3b0 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53  lso used as a [S
1d3c0 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c  QLITE_ROLLBACK |
1d3d0 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a   return code].**
1d3e0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1d3f0 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
1d400 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
1d410 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1d420 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
1d430 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
1d440 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
1d450 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
1d460 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
1d470 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
1d480 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
1d490 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
1d4a0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
1d4b0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1d4c0 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
1d4d0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1d4e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1d4f0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
1d500 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
1d510 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1d520 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
1d530 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
1d540 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
1d550 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
1d560 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1d570 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1d580 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1d590 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
1d5a0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1d5b0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
1d5c0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
1d5d0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
1d5e0 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
1d5f0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
1d600 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d610 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
1d620 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
1d630 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
1d640 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
1d650 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
1d660 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
1d670 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
1d680 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
1d690 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
1d6a0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
1d6b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1d6c0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1d6d0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1d6e0 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
1d6f0 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
1d700 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1d710 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1d720 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
1d730 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
1d740 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d750 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
1d760 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
1d770 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
1d780 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
1d790 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
1d7a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1d7b0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1d7c0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
1d7d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
1d7e0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1d7f0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1d800 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1d810 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
1d820 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
1d830 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
1d840 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
1d850 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
1d860 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1d870 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1d880 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d890 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1d8a0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1d8b0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1d8c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1d8d0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1d8e0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1d8f0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1d900 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1d910 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1d920 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1d930 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1d940 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1d950 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d960 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1d970 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1d980 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1d990 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1d9a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1d9b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1d9c0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1d9d0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1d9e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1d9f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1da00 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1da10 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1da20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1da30 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1da40 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1da50 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1da60 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1da70 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1da80 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1da90 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1daa0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1dab0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1dac0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1dad0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1dae0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1daf0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1db00 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1db10 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1db20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1db30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1db40 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1db50 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1db60 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1db70 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1db80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1db90 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1dba0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1dbb0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1dbc0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1dbd0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1dbe0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1dbf0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1dc00 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1dc10 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1dc20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1dc30 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1dc40 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1dc50 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1dc60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1dc70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dc80 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1dc90 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1dca0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dcb0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1dcc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dcd0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1dce0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1dcf0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1dd00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1dd10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dd20 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1dd30 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1dd40 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1dd50 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1dd60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dd70 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1dd80 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1dd90 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1dda0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ddb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ddc0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1ddd0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1dde0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1ddf0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1de00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1de10 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1de20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1de30 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1de40 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1de50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1de60 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1de70 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1de80 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1de90 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1dea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1deb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dec0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1ded0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1dee0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1def0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1df00 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1df10 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1df20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1df30 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1df40 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1df50 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1df60 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1df70 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1df80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1df90 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1dfa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1dfb0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1dfc0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1dfd0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1dfe0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1dff0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1e000 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1e010 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e020 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e030 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1e040 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1e050 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1e060 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1e070 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e080 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1e090 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1e0a0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1e0b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1e0c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e0d0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1e0e0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1e0f0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1e100 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e110 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e120 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1e130 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1e140 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e150 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e160 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e170 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1e180 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1e190 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e1a0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1e1b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e1c0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1e1d0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1e1e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1e1f0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1e200 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e210 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1e220 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1e230 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1e240 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1e250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e260 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
1e270 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
1e280 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
1e290 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
1e2a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1e2b0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
1e2c0 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
1e2d0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
1e2e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e2f0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
1e300 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
1e310 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1e320 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1e330 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1e340 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1e350 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1e360 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1e370 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1e380 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1e390 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1e3a0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1e3b0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1e3c0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
1e3d0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
1e3e0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
1e3f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1e400 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
1e410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1e420 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e430 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1e440 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
1e450 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
1e460 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
1e470 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
1e480 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
1e490 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
1e4a0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
1e4b0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
1e4c0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1e4d0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
1e4e0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
1e4f0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
1e500 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
1e510 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
1e520 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
1e530 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
1e540 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
1e550 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
1e560 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er.)^.**.** ^The
1e570 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e580 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1e590 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1e5a0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1e5b0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
1e5c0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
1e5d0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1e5e0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
1e5f0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
1e600 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1e610 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
1e620 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
1e630 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
1e640 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
1e650 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
1e660 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1e670 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
1e680 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
1e690 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
1e6a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
1e6b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
1e6c0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
1e6d0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
1e6e0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
1e6f0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
1e700 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
1e710 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
1e720 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
1e730 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1e740 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
1e750 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
1e760 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
1e770 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
1e780 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
1e790 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1e7a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
1e7b0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
1e7c0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
1e7d0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
1e7e0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
1e7f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
1e800 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1e810 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
1e820 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
1e830 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
1e840 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
1e850 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
1e860 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1e870 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1e880 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
1e890 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
1e8a0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
1e8b0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
1e8c0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
1e8d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e8e0 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
1e8f0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1e900 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
1e910 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
1e920 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
1e930 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
1e940 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1e950 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
1e960 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1e970 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
1e980 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
1e990 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1e9a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e9b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
1e9c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
1e9d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1e9e0 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
1e9f0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
1ea00 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
1ea10 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
1ea20 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
1ea30 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
1ea40 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
1ea50 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
1ea60 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
1ea70 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
1ea80 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
1ea90 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
1eaa0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
1eab0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1eac0 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
1ead0 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
1eae0 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
1eaf0 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
1eb00 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
1eb10 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
1eb20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a  callback X..**.*
1eb30 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
1eb40 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1eb50 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
1eb60 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
1eb70 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1eb80 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
1eb90 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
1eba0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
1ebb0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
1ebc0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
1ebd0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
1ebe0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
1ebf0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1ec00 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
1ec10 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
1ec20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
1ec30 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
1ec40 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
1ec50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
1ec60 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1ec70 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1ec80 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
1ec90 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
1eca0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
1ecb0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1ecc0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
1ecd0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
1ece0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
1ecf0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
1ed00 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
1ed10 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1ed20 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1ed30 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1ed40 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1ed50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ed60 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1ed70 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1ed80 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1ed90 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1eda0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1edb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1edc0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1edd0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1ede0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1edf0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1ee00 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1ee10 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51  agraph..**.*/.SQ
1ee20 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1ee30 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1ee40 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1ee50 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1ee60 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1ee70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1ee80 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1ee90 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
1eea0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1eeb0 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
1eec0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
1eed0 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
1eee0 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
1eef0 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
1ef00 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1ef10 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
1ef20 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
1ef30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1ef40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1ef50 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
1ef60 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1ef70 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
1ef80 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
1ef90 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
1efa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1efb0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
1efc0 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
1efd0 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
1efe0 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
1eff0 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
1f000 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
1f010 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
1f020 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1f030 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
1f040 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
1f050 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
1f060 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
1f070 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
1f080 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
1f090 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1f0a0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
1f0b0 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
1f0c0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1f0d0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1f0e0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1f0f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1f100 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1f110 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1f120 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1f130 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
1f140 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1f150 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1f160 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
1f170 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
1f180 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
1f190 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
1f1a0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
1f1b0 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
1f1c0 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
1f1d0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
1f1e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
1f1f0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
1f200 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1f210 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1f220 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1f230 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1f240 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1f250 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1f260 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1f270 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1f280 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1f290 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1f2a0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1f2b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1f2c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1f2d0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1f2e0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1f2f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1f300 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1f310 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1f320 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1f330 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1f340 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1f350 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1f360 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1f370 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1f380 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f390 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1f3a0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1f3b0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1f3c0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1f3d0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1f3e0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1f3f0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1f400 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1f410 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1f420 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
1f430 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
1f440 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1f450 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
1f460 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
1f470 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
1f480 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
1f490 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
1f4a0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
1f4b0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
1f4c0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1f4d0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1f4e0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
1f4f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1f500 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
1f510 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
1f520 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
1f530 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
1f540 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1f550 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
1f560 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1f570 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1f580 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
1f590 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
1f5a0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1f5b0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
1f5c0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1f5d0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1f5e0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1f5f0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
1f600 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1f610 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1f620 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1f630 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1f640 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
1f650 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
1f660 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
1f670 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1f680 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1f690 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
1f6a0 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
1f6b0 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
1f6c0 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
1f6d0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1f6e0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1f6f0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1f700 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1f710 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1f720 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1f730 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1f740 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1f750 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1f760 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1f770 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
1f780 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
1f790 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
1f7a0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
1f7b0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
1f7c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1f7d0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1f7e0 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
1f7f0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
1f800 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
1f810 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1f820 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
1f830 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
1f840 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1f850 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
1f860 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1f870 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
1f880 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
1f890 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
1f8a0 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
1f8b0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
1f8c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
1f8d0 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
1f8e0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
1f8f0 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
1f900 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f910 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
1f920 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
1f930 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
1f940 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
1f950 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
1f960 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
1f970 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
1f980 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1f990 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
1f9a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1f9b0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
1f9c0 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
1f9d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f9e0 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
1f9f0 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
1fa00 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1fa10 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
1fa20 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
1fa30 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
1fa40 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
1fa50 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1fa60 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
1fa70 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1fa80 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
1fa90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1faa0 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
1fab0 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
1fac0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1fad0 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
1fae0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1faf0 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
1fb00 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
1fb10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
1fb20 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
1fb30 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
1fb40 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1fb50 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
1fb60 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
1fb70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
1fb80 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
1fb90 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
1fba0 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
1fbb0 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
1fbc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
1fbd0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1fbe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1fbf0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
1fc00 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1fc10 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
1fc20 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
1fc30 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1fc40 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
1fc50 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1fc60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
1fc70 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
1fc80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1fc90 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
1fca0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
1fcb0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1fcc0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
1fcd0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
1fce0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1fcf0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1fd00 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1fd10 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
1fd20 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
1fd30 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
1fd40 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
1fd50 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
1fd60 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
1fd70 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
1fd80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fd90 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
1fda0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1fdb0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
1fdc0 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
1fdd0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
1fde0 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
1fdf0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
1fe00 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
1fe10 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
1fe20 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
1fe30 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1fe40 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
1fe50 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
1fe60 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
1fe70 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
1fe80 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
1fe90 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
1fea0 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
1feb0 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
1fec0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1fed0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1fee0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1fef0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1ff00 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1ff10 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1ff20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
1ff30 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
1ff40 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
1ff50 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
1ff60 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
1ff70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ff80 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1ff90 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
1ffa0 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
1ffb0 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
1ffc0 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
1ffd0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
1ffe0 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
1fff0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
20000 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
20010 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
20020 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
20030 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
20040 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
20050 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
20060 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
20070 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
20080 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
20090 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
200a0 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
200b0 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
200c0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
200d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
200e0 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
200f0 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
20100 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
20110 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
20120 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
20130 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
20140 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
20150 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
20160 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
20170 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
20180 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
20190 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
201a0 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
201b0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
201c0 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
201d0 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
201e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
201f0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
20200 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
20210 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
20220 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
20230 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
20240 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
20250 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
20260 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
20270 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
20280 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
20290 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
202a0 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
202b0 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
202c0 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
202d0 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
202e0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
202f0 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
20300 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
20310 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
20320 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
20330 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
20340 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
20350 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
20360 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
20370 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
20380 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
20390 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
203a0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
203b0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
203c0 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
203d0 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
203e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
203f0 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
20400 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
20410 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
20420 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
20430 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
20440 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
20450 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
20460 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
20470 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
20480 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
20490 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
204a0 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
204b0 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
204c0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
204d0 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
204e0 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
204f0 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
20500 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
20510 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  ^On windows, the
20520 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
20530 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
20540 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
20550 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
20560 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a  n (e.g. "C:")..*
20570 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
20580 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
20590 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
205a0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
205b0 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
205c0 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
205d0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
205e0 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
205f0 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
20600 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
20610 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
20620 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
20630 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66  interprets the f
20640 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71  ollowing three q
20650 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
20660 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
20670 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
20680 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
20690 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
206a0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
206b0 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
206c0 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
206d0 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
206e0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
206f0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
20700 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
20710 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
20720 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
20730 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
20740 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
20750 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
20760 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
20770 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
20780 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
20790 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
207a0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
207b0 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
207c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
207d0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
207e0 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
207f0 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
20800 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
20810 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
20820 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
20830 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
20840 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
20850 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
20860 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
20870 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
20880 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
20890 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
208a0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
208b0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
208c0 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
208d0 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
208e0 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
208f0 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
20900 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
20910 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
20920 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
20930 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
20940 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
20950 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20960 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
20970 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
20980 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
20990 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
209a0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
209b0 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
209c0 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
209d0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
209e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
209f0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
20a00 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
20a10 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
20a20 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20a30 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
20a40 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
20a50 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
20a60 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
20a70 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
20a80 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
20a90 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
20aa0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
20ab0 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
20ac0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
20ad0 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
20ae0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
20af0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
20b00 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
20b10 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
20b20 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
20b30 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
20b40 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
20b50 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
20b60 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
20b70 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
20b80 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
20b90 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
20ba0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
20bb0 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
20bc0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
20bd0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
20be0 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
20bf0 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
20c00 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
20c10 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
20c20 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
20c30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
20c40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
20c50 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
20c60 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
20c70 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
20c80 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
20c90 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
20ca0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
20cb0 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
20cc0 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
20cd0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
20ce0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
20cf0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
20d00 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
20d10 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
20d20 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
20d30 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
20d40 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
20d50 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
20d60 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
20d70 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
20d80 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
20d90 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
20da0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
20db0 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
20dc0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20dd0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
20de0 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
20df0 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
20e00 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
20e10 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
20e20 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
20e30 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
20e40 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
20e50 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
20e60 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
20e70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
20e80 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
20e90 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
20ea0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
20eb0 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
20ec0 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
20ed0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
20ee0 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
20ef0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
20f00 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
20f10 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
20f20 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
20f30 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
20f40 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
20f50 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
20f60 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
20f70 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
20f80 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
20f90 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
20fa0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
20fb0 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
20fc0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
20fd0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
20fe0 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
20ff0 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
21000 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
21010 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
21020 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
21030 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
21040 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
21050 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
21060 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
21070 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
21080 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
21090 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
210a0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
210b0 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
210c0 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
210d0 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
210e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
210f0 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
21100 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
21110 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
21120 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
21130 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
21140 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21150 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
21160 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
21170 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21180 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
21190 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
211a0 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
211b0 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
211c0 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
211d0 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
211e0 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
211f0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
21200 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
21210 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
21220 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
21230 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
21240 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
21250 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
21260 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
21270 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
21280 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
21290 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
212a0 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
212b0 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
212c0 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
212d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
212e0 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
212f0 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
21300 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
21310 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
21320 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
21330 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
21340 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
21350 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
21360 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
21370 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
21380 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
21390 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
213a0 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
213b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
213c0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
213d0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
213e0 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
213f0 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
21400 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
21410 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
21420 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
21430 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
21440 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
21450 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20  -nolock <td>.** 
21460 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
21470 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
21480 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
21490 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
214a0 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c  ix-nolock"..** <
214b0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
214c0 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
214d0 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
214e0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
214f0 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
21500 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
21510 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
21520 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
21530 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
21540 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
21550 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
21560 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
21570 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
21580 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
21590 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
215a0 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
215b0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
215c0 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
215d0 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
215e0 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
215f0 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
21600 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
21610 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
21620 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
21630 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
21640 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
21650 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
21660 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
21670 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
21680 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
21690 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
216a0 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
216b0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
216c0 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
216d0 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
216e0 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
216f0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
21700 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
21710 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
21720 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
21730 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
21740 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
21750 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
21760 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
21770 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
21780 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
21790 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
217a0 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
217b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
217c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
217d0 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
217e0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
217f0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
21800 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
21810 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
21820 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
21830 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
21840 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
21850 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
21860 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
21870 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
21880 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
21890 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
218a0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
218b0 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
218c0 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
218d0 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
218e0 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
218f0 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
21900 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
21910 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
21920 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
21930 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
21940 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
21950 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
21960 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
21970 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
21980 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
21990 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
219a0 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tory].*/.SQLITE_
219b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
219c0 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
219d0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
219e0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
219f0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
21a00 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
21a10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
21a20 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
21a30 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
21a40 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
21a50 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
21a60 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
21a70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
21a80 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
21a90 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
21aa0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
21ab0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
21ac0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
21ad0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
21ae0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
21af0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
21b00 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
21b10 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
21b20 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
21b30 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
21b40 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
21b50 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
21b60 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
21b70 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
21b80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
21b90 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
21ba0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
21bb0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
21bc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21bd0 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
21be0 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
21bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
21c00 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
21c10 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
21c20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
21c30 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
21c40 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
21c50 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
21c60 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
21c70 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
21c80 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
21c90 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
21ca0 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
21cb0 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
21cc0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
21cd0 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
21ce0 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
21cf0 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
21d00 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
21d10 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
21d20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
21d30 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
21d40 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
21d50 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
21d60 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
21d70 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
21d80 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
21d90 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
21da0 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
21db0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
21dc0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
21dd0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
21de0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
21df0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
21e00 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
21e10 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
21e20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
21e30 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
21e40 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
21e50 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
21e60 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
21e70 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
21e80 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
21e90 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
21ea0 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
21eb0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
21ec0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
21ed0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
21ee0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
21ef0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
21f00 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
21f10 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
21f20 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
21f30 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
21f40 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
21f50 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
21f60 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
21f70 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
21f80 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
21f90 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
21fa0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
21fb0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
21fc0 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
21fd0 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
21fe0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
21ff0 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
22000 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
22010 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
22020 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
22030 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
22040 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
22050 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
22060 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
22070 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
22080 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
22090 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
220a0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
220b0 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
220c0 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
220d0 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
220e0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
220f0 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
22100 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
22110 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
22120 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
22130 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
22140 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
22150 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
22160 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
22170 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
22180 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
22190 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
221a0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
221b0 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
221c0 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
221d0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
221e0 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
221f0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
22200 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
22210 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
22220 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
22230 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
22240 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
22250 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
22260 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
22270 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
22280 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
22290 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
222a0 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
222b0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
222c0 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
222d0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
222e0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
222f0 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
22300 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
22310 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
22320 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
22330 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
22340 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
22350 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
22360 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
22370 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
22380 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
22390 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
223a0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
223b0 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
223c0 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ble..*/.SQLITE_A
223d0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
223e0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
223f0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
22400 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
22410 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
22420 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
22430 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
22440 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
22450 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
22460 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
22470 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45  Default);.SQLITE
22480 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
22490 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
224a0 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
224b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
224c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
224d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
224e0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
224f0 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
22500 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
22510 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
22520 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
22530 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
22540 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
22550 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
22560 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
22570 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
22580 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
22590 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
225a0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
225b0 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
225c0 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
225d0 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
225e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
225f0 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
22600 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
22610 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
22620 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
22630 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
22640 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
22650 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
22660 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
22670 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
22680 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
22690 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
226a0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
226b0 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
226c0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
226d0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
226e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
226f0 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
22700 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
22710 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
22720 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
22730 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
22740 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
22750 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
22760 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
22770 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
22780 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
22790 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
227a0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
227b0 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
227c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
227d0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
227e0 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
227f0 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
22800 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
22810 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
22820 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
22830 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
22840 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
22850 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
22860 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
22870 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
22880 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22890 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
228a0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
228b0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
228c0 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
228d0 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
228e0 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
228f0 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
22900 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
22910 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
22920 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
22930 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
22940 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
22950 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
22960 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
22970 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
22980 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
22990 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
229a0 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
229b0 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
229c0 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
229d0 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
229e0 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
229f0 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
22a00 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
22a10 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
22a20 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
22a30 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
22a40 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
22a50 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
22a60 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
22a70 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
22a80 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
22a90 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
22aa0 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
22ab0 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
22ac0 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
22ad0 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
22ae0 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
22af0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
22b00 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
22b10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
22b20 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
22b30 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
22b40 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
22b50 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
22b60 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
22b70 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
22b80 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
22b90 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
22ba0 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
22bb0 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
22bc0 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
22bd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
22be0 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
22bf0 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
22c00 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
22c10 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
22c20 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
22c30 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
22c40 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
22c50 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
22c60 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
22c70 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
22c80 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
22c90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
22ca0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
22cb0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51  sqlite3 *db);.SQ
22cc0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
22cd0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
22ce0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
22cf0 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  b);.SQLITE_API c
22d00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22d10 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
22d20 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
22d30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
22d40 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
22d50 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
22d60 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
22d70 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
22d80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
22d90 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
22da0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
22db0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
22dc0 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
22dd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
22de0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
22df0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
22e00 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
22e10 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
22e20 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
22e30 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
22e40 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
22e50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22e60 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
22e70 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
22e80 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
22e90 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
22ea0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
22eb0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
22ec0 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
22ed0 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
22ee0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
22ef0 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
22f00 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
22f10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
22f20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
22f30 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
22f40 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
22f50 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
22f60 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
22f70 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
22f80 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
22f90 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
22fa0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
22fb0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
22fc0 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
22fd0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
22fe0 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
22ff0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
23000 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
23010 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
23020 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
23030 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
23040 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
23050 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
23060 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
23070 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
23080 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
23090 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
230a0 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
230b0 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
230c0 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
230d0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
230e0 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
230f0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
23100 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
23110 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23120 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
23130 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
23140 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
23150 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
23160 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
23170 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
23180 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
23190 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
231a0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
231b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
231c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
231d0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
231e0 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
231f0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
23200 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
23210 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
23220 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
23230 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
23240 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
23250 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
23260 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
23270 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
23280 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
23290 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
232a0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
232b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
232c0 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
232d0 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
232e0 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
232f0 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
23300 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
23310 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
23320 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
23330 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
23340 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
23350 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
23360 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
23370 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
23380 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
23390 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
233a0 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
233b0 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
233c0 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
233d0 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
233e0 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
233f0 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
23400 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
23410 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
23420 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
23430 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
23440 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
23450 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
23460 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
23470 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
23480 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
23490 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
234a0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
234b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
234c0 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
234d0 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
234e0 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
234f0 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
23500 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
23510 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
23520 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
23530 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
23540 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
23550 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
23560 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
23570 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
23580 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
23590 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
235a0 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
235b0 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
235c0 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
235d0 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
235e0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
235f0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
23600 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
23610 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
23620 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
23630 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
23640 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
23650 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
23660 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
23670 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
23680 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
23690 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
236a0 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
236b0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
236c0 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
236d0 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
236e0 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
236f0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
23700 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
23710 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
23720 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
23730 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
23740 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
23750 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
23760 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
23770 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
23780 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
23790 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
237a0 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
237b0 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
237c0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
237d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
237e0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
237f0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
23800 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
23810 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
23820 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
23830 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
23840 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
23850 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
23860 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
23870 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
23880 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
23890 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
238a0 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
238b0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
238c0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51   releases..*/.SQ
238d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
238e0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
238f0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
23900 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
23910 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
23920 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
23930 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
23940 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
23950 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
23960 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
23970 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
23980 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
23990 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
239a0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
239b0 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
239c0 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
239d0 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
239e0 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
239f0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
23a00 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
23a10 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
23a20 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
23a30 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
23a40 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
23a50 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
23a60 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
23a70 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
23a80 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
23a90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23aa0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
23ab0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23ac0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
23ad0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
23ae0 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
23af0 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
23b00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
23b10 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
23b20 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
23b30 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
23b40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
23b50 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
23b60 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
23b70 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
23b80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23b90 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
23ba0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
23bb0 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
23bc0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
23bd0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
23be0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
23bf0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
23c00 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
23c10 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
23c20 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
23c30 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
23c40 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
23c50 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
23c60 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
23c70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
23c80 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
23c90 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
23ca0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
23cb0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
23cc0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
23cd0 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
23ce0 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
23cf0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
23d00 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
23d10 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
23d20 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
23d30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
23d40 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
23d50 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
23d60 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
23d70 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
23d80 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
23d90 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
23da0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23db0 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
23dc0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
23dd0 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
23de0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
23df0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
23e00 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
23e10 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
23e20 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
23e30 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
23e40 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c  atement.  This l
23e50 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72  imit is not curr
23e60 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65  ently.** enforce
23e70 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d  d, though that m
23e80 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e  ight be added in
23e90 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
23ea0 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
23eb0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
23ec0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
23ed0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
23ee0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23ef0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
23f00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23f10 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23f20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
23f30 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
23f40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
23f50 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
23f60 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23f70 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
23f80 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23f90 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
23fa0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
23fb0 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
23fc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
23fd0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
23fe0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
23ff0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
24000 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
24010 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
24020 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24030 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
24040 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
24050 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
24060 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
24070 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
24080 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24090 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
240a0 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
240b0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
240c0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
240d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
240e0 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
240f0 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
24100 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
24110 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
24120 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
24130 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
24140 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
24150 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
24160 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24170 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
24180 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
24190 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
241a0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
241b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
241c0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
241d0 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
241e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
241f0 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
24200 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
24210 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24220 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
24230 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
24240 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24250 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
24260 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
24270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24280 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
24290 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
242a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
242b0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
242c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
242d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
242e0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
242f0 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
24300 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
24310 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
24320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24330 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
24340 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
24350 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
24360 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
24370 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
24380 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
24390 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
243a0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
243b0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
243c0 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     10../*.** CAP
243d0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
243e0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
243f0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
24400 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
24410 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
24420 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
24430 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
24440 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
24450 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
24460 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
24470 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
24480 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
24490 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
244a0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
244b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
244c0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
244d0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
244e0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
244f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
24500 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
24510 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
24520 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
24530 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
24540 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
24550 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
24560 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
24570 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
24580 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
24590 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
245a0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
245b0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
245c0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
245d0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
245e0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
245f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
24600 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
24610 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
24620 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
24630 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
24640 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
24650 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
24660 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
24670 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
24680 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
24690 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
246a0 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
246b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
246c0 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  ^If nByte is non
246d0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
246e0 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
246f0 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
24700 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
24710 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79  zSql.  ^When nBy
24720 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
24730 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
24740 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
24750 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
24760 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
24770 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
24780 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
24790 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
247a0 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
247b0 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
247c0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
247d0 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
247e0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
247f0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
24800 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
24810 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
24820 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
24830 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
24840 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
24850 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
24860 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
24870 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
24880 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
24890 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
248a0 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
248b0 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73  es as this saves
248c0 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76   SQLite from hav
248d0 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61  ing to.** make a
248e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70   copy of the inp
248f0 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ut string..**.**
24900 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
24910 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
24920 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
24930 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
24940 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
24950 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
24960 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
24970 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
24980 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
24990 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
249a0 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
249b0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
249c0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
249d0 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
249e0 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
249f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
24a00 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
24a10 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
24a20 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
24a30 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
24a40 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
24a50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
24a60 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
24a70 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
24a80 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
24a90 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
24aa0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
24ab0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
24ac0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
24ad0 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
24ae0 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
24af0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
24b00 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
24b10 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
24b20 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
24b30 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
24b40 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
24b50 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
24b60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
24b70 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
24b80 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
24b90 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
24ba0 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
24bb0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
24bc0 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
24bd0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
24be0 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
24bf0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
24c00 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
24c10 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
24c20 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
24c30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24c40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
24c50 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
24c60 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
24c70 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
24c80 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
24c90 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
24ca0 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
24cb0 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
24cc0 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
24cd0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
24ce0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
24cf0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
24d00 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
24d10 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
24d20 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
24d30 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
24d40 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
24d50 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
24d60 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
24d70 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
24d80 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
24d90 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
24da0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24db0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
24dc0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
24dd0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
24de0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
24df0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
24e00 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
24e10 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
24e20 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
24e30 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
24e40 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
24e50 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
24e60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
24e70 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
24e80 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
24e90 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
24ea0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
24eb0 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e   again..** </li>
24ec0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
24ed0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
24ee0 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
24ef0 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
24f00 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
24f10 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
24f20 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
24f30 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
24f40 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
24f50 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
24f60 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
24f70 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
24f80 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
24f90 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
24fa0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
24fb0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
24fc0 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
24fd0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
24fe0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
24ff0 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
25000 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
25010 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
25020 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
25030 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
25040 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
25050 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
25060 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
25070 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
25080 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
25090 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
250a0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
250b0 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
250c0 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
250d0 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
250e0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
250f0 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
25100 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
25110 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
25120 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
25130 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
25140 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
25150 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
25160 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
25170 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
25180 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
25190 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
251a0 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
251b0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
251c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
251d0 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
251e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
251f0 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
25200 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
25210 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
25220 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
25230 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
25240 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
25250 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
25260 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
25270 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
25280 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
25290 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
252a0 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
252b0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
252c0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
252d0 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
252e0 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
252f0 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
25300 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
25310 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
25320 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
25330 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c  ed..** the .** <
25340 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
25350 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
25360 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
25370 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
25380 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
25390 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
253a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
253b0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
253c0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
253d0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
253e0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
253f0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
25400 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
25410 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
25420 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
25430 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
25440 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
25450 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
25460 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
25470 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
25480 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
25490 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
254a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
254b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
254c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
254d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
254e0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
254f0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
25500 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
25510 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
25520 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
25530 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
25540 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
25550 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
25560 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
25570 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
25580 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
25590 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
255a0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
255b0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
255c0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
255d0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
255e0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
255f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
25600 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25610 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
25620 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
25630 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
25640 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
25650 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
25660 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
25670 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
25680 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
25690 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
256a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
256b0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
256c0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
256d0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
256e0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
256f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
25700 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
25710 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
25720 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
25730 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
25740 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
25750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25760 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
25770 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
25780 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
25790 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
257a0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
257b0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
257c0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
257d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
257e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
257f0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
25800 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
25810 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
25820 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
25830 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
25840 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25850 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
25860 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
25870 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
25880 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
25890 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
258a0 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
258b0 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
258c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
258d0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
258e0 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
258f0 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
25900 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
25910 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
25920 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
25930 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
25940 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
25950 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
25960 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
25970 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25980 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
25990 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
259a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
259b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
259c0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
259d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
259e0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
259f0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
25a00 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
25a10 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
25a20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
25a30 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
25a40 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
25a50 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
25a60 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
25a70 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
25a80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
25a90 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
25aa0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
25ab0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
25ac0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
25ad0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
25ae0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
25af0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
25b00 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
25b10 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
25b20 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
25b30 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
25b40 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
25b50 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
25b60 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
25b70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
25b80 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
25b90 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
25ba0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
25bb0 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
25bc0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
25bd0 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
25be0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
25bf0 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
25c00 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
25c10 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
25c20 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
25c30 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
25c40 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
25c50 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
25c60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
25c70 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
25c80 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
25c90 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
25ca0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
25cb0 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
25cc0 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
25cd0 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
25ce0 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
25cf0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
25d00 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
25d10 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
25d20 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
25d30 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
25d40 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
25d50 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
25d60 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
25d70 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
25d80 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
25d90 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
25da0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
25db0 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
25dc0 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
25dd0 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
25de0 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
25df0 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
25e00 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
25e10 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
25e20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
25e30 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
25e40 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
25e50 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
25e60 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
25e70 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
25e80 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
25e90 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
25ea0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
25eb0 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
25ec0 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
25ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
25ee0 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
25ef0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
25f00 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
25f10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
25f20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49  on disk..*/.SQLI
25f30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
25f40 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
25f50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
25f60 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
25f70 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
25f80 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
25f90 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
25fa0 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  en Reset.**.** ^
25fb0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
25fc0 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
25fd0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
25fe0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
25ff0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
26000 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
26010 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
26020 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
26030 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
26040 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
26050 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  ot run to comple
26060 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20  tion and/or has 
26070 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73  not .** been res
26080 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
26090 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
260a0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
260b0 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
260c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
260d0 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
260e0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
260f0 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
26100 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
26110 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
26120 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
26130 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
26140 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
26150 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
26160 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
26170 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
26180 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
26190 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
261a0 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
261b0 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
261c0 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
261d0 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
261e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
261f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
26200 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
26210 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
26220 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
26230 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
26240 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
26250 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
26260 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
26270 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
26280 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
26290 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
262a0 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
262b0 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
262c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
262d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
262e0 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
262f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26300 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
26310 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
26320 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
26330 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
26340 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
26350 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26360 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
26370 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
26380 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
26390 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
263a0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
263b0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
263c0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
263d0 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
263e0 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
263f0 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
26400 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
26410 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
26420 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26430 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
26440 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
26450 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
26460 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
26470 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
26480 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
26490 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
264a0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
264b0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
264c0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
264d0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
264e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
264f0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
26500 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
26510 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
26520 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
26530 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
26540 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
26550 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
26560 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
26570 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
26580 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
26590 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
265a0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
265b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
265c0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
265d0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
265e0 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
265f0 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
26600 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
26610 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
26620 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
26630 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
26640 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
26650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26660 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
26670 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
26680 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
26690 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
266a0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
266b0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
266c0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
266d0 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
266e0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
266f0 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
26700 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
26710 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
26720 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
26730 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
26740 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
26750 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
26760 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
26770 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
26780 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
26790 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
267a0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
267b0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
267c0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
267d0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
267e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
267f0 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
26800 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
26810 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
26820 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
26830 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
26840 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
26850 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
26860 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
26870 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
26880 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
26890 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
268a0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
268b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
268c0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
268d0 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
268e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
268f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
26900 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
26910 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
26920 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
26930 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
26940 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26950 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
26960 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
26970 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
26980 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
26990 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
269a0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
269b0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
269c0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
269d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
269e0 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
269f0 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
26a00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
26a10 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
26a20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
26a30 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
26a40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
26a50 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
26a60 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
26a70 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
26a80 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
26a90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26aa0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
26ab0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
26ac0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
26ad0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26ae0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
26af0 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
26b00 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
26b10 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
26b20 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
26b30 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
26b40 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
26b50 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
26b60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
26b70 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
26b80 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
26b90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
26ba0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
26bb0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
26bc0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
26bd0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26be0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
26bf0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26c00 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
26c10 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
26c20 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
26c30 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
26c40 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
26c50 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
26c60 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
26c70 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
26c80 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
26c90 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
26ca0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
26cb0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
26cc0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
26cd0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
26ce0 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
26cf0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
26d00 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
26d10 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
26d20 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
26d30 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
26d40 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
26d50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
26d60 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
26d70 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
26d80 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
26d90 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
26da0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
26db0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
26dc0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
26dd0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
26de0 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
26df0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
26e00 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
26e10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26e20 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
26e30 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
26e40 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
26e50 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
26e60 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
26e70 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
26e80 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
26e90 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
26ea0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
26eb0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
26ec0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
26ed0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
26ee0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
26ef0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
26f00 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
26f10 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
26f20 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
26f30 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
26f40 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
26f50 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
26f60 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
26f70 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
26f80 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
26f90 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
26fa0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
26fb0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
26fc0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
26fd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
26fe0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
26ff0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
27000 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
27010 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
27020 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
27030 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
27040 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
27050 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
27060 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
27070 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
27080 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
27090 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
270a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
270b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
270c0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
270d0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
270e0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
270f0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
27100 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
27110 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
27120 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
27130 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
27140 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
27150 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
27160 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
27170 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
27180 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
27190 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
271a0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
271b0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
271c0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
271d0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
271e0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
271f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27200 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
27210 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
27220 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
27230 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
27240 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
27250 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
27260 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
27270 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
27280 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
27290 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
272a0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
272b0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
272c0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
272d0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
272e0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
272f0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
27300 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
27310 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ameter..**.** ^(
27320 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
27330 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
27340 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
27350 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
27360 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
27370 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
27380 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
27390 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
273a0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
273b0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
273c0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
273d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
273e0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
273f0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
27400 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
27410 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
27420 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
27430 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
27440 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
27450 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
27460 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
27470 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
27480 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
27490 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
274a0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
274b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
274c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
274d0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
274e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
274f0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
27500 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
27510 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
27520 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
27530 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
27540 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
27550 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
27560 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61  ext16() then tha
27570 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
27580 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
27590 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
275a0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
275b0 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
275c0 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
275d0 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
275e0 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
275f0 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
27600 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
27610 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
27620 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
27630 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
27640 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
27650 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
27660 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
27670 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
27680 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
27690 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
276a0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
276b0 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
276c0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
276d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
276e0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
276f0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
27700 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
27710 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
27720 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
27730 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
27740 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
27750 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
27760 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
27770 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
27780 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
27790 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
277a0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
277b0 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
277c0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
277d0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
277e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
277f0 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
27800 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27810 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
27820 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
27830 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
27840 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
27850 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
27860 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
27870 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
27880 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
27890 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
278a0 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
278b0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
278c0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
278d0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
278e0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
278f0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
27900 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
27910 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
27920 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
27930 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
27940 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
27950 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
27960 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
27970 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
27980 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
27990 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
279a0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
279b0 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
279c0 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
279d0 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
279e0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
279f0 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
27a00 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
27a10 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
27a20 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
27a30 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
27a40 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
27a50 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
27a60 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
27a70 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
27a80 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
27a90 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
27aa0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
27ab0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
27ac0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
27ad0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
27ae0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
27af0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
27b00 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
27b10 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
27b20 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
27b30 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
27b40 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
27b50 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
27b60 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
27b70 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
27b80 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
27b90 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
27ba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27bb0 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
27bc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27bd0 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
27be0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
27bf0 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
27c00 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
27c10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27c20 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
27c30 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
27c40 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
27c50 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
27c60 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
27c70 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
27c80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27c90 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
27ca0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
27cb0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
27cc0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
27cd0 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
27ce0 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
27cf0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
27d00 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
27d10 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
27d20 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
27d30 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
27d40 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
27d50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
27d60 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
27d70 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
27d80 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
27d90 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
27da0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
27db0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
27dc0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
27dd0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
27de0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
27df0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
27e00 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
27e10 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
27e20 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
27e30 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
27e40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
27e50 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
27e60 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
27e70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
27e80 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
27e90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
27ea0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
27eb0 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
27ec0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27ed0 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
27ee0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
27ef0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
27f00 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
27f10 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
27f20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27f30 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
27f40 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
27f50 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  e);.SQLITE_API i
27f60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27f70 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
27f80 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51  *, int, int);.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 69 6e 74 36 34 28  ite3_bind_int64(
27fb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27fc0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
27fd0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  4);.SQLITE_API i
27fe0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27ff0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
28000 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
28010 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28020 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
28030 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
28040 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
28050 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
28060 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
28070 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28080 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
28090 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
280a0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
280b0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
280c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
280d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
280e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
280f0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
28100 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
28110 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
28120 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
28130 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28140 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
28150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
28160 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
28170 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
28180 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
28190 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
281a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
281b0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
281c0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
281d0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
281e0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
281f0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
28200 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
28210 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
28220 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
28230 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
28240 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
28250 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
28260 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28270 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
28280 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
28290 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
282a0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
282b0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
282c0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
282d0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
282e0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
282f0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
28300 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
28310 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
28320 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
28330 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
28340 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
28350 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
28360 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
28370 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
28380 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
28390 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
283a0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
283b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
283c0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
283d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
283e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
283f0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
28400 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28410 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
28420 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
28430 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
28440 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
28450 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
28460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
28470 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
28480 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
28490 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
284a0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
284b0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
284c0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
284d0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
284e0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
284f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28500 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
28510 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
28520 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
28530 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
28540 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
28550 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
28560 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
28570 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
28580 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
28590 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
285a0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
285b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
285c0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
285d0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
285e0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
285f0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
28600 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
28610 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
28620 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
28630 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
28640 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
28650 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
28660 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
28670 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
28680 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
28690 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
286a0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
286b0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
286c0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
286d0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
286e0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
286f0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
28700 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
28710 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
28720 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
28730 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
28740 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
28750 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
28760 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
28770 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
28780 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
28790 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
287a0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
287b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
287c0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
287d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
287e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
287f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28800 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
28810 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28820 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28830 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
28840 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
28850 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
28860 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
28870 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
28880 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28890 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
288a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
288b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
288c0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
288d0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
288e0 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
288f0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
28900 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
28910 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
28920 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
28930 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
28940 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
28950 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
28960 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
28970 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
28980 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
28990 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
289a0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
289b0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
289c0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
289d0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
289e0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
289f0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
28a00 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
28a10 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
28a20 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
28a30 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
28a40 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
28a50 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
28a60 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
28a70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
28a80 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
28a90 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
28aa0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
28ab0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
28ac0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28ad0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
28ae0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
28af0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28b00 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28b10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28b20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
28b30 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
28b40 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
28b50 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
28b60 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
28b70 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
28b80 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
28b90 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
28ba0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
28bb0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
28bc0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
28bd0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
28be0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
28bf0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
28c00 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
28c10 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
28c20 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
28c30 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45   NULL..*/.SQLITE
28c40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28c50 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
28c60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
28c70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28c80 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
28c90 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
28ca0 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
28cb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
28cc0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
28cd0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
28ce0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
28cf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28d00 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
28d10 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
28d20 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
28d30 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
28d40 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
28d50 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
28d60 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
28d70 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
28d80 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
28d90 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
28da0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28db0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
28dc0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
28dd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28de0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
28df0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
28e00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
28e10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
28e20 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
28e30 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
28e40 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
28e50 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
28e60 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
28e70 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
28e80 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
28e90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
28ea0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
28eb0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
28ec0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
28ed0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
28ee0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
28ef0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
28f00 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
28f10 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
28f20 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
28f30 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
28f40 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
28f50 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
28f60 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
28f70 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
28f80 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
28f90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
28fa0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
28fb0 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
28fc0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
28fd0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
28fe0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
28ff0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
29000 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
29010 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
29020 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
29030 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
29040 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29050 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
29060 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
29070 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
29080 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
29090 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
290a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
290b0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
290c0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
290d0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
290e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
290f0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
29100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29110 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
29120 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
29130 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
29140 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
29150 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
29160 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
29170 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
29180 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
29190 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
291a0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
291b0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
291c0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
291d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
291e0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
291f0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
29200 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
29210 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
29220 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
29230 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
29240 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
29250 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
29260 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
29270 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
29280 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
29290 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
292a0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
292b0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
292c0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
292d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
292e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
292f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29300 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
29310 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
29320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
29330 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
29340 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
29350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
29360 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
29370 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
29380 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
29390 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
293a0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
293b0 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
293c0 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
293d0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
293e0 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
293f0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
29400 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
29410 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
29420 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
29430 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
29440 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
29450 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
29460 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
29470 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
29480 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
29490 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
294a0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
294b0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
294c0 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
294d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
294e0 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
294f0 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
29500 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
29510 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
29520 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
29530 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
29540 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
29550 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29560 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
29570 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
29580 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
29590 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
295a0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
295b0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
295c0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
295d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
295e0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
295f0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
29600 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
29610 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
29620 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
29630 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
29640 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
29650 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
29660 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
29670 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
29680 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
29690 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
296a0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
296b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
296c0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
296d0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
296e0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
296f0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
29700 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
29710 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
29720 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
29730 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
29740 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
29750 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
29760 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
29770 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
29780 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
29790 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
297a0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
297b0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
297c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
297d0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
297e0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
297f0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
29800 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
29810 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
29820 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
29830 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
29840 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
29850 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
29860 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
29870 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
29880 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
29890 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
298a0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
298b0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
298c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
298d0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
298e0 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
298f0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
29900 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
29910 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
29920 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
29930 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
29940 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
29950 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
29960 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
29970 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
29980 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
29990 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
299a0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
299b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
299c0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
299d0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
299e0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
299f0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
29a00 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
29a10 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
29a20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
29a30 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
29a40 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
29a50 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
29a60 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
29a70 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
29a80 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
29a90 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
29aa0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
29ab0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
29ac0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
29ad0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
29ae0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
29af0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
29b00 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
29b10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
29b20 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
29b30 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
29b40 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
29b50 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
29b60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
29b70 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
29b80 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
29b90 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
29ba0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
29bb0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
29bc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
29bd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
29be0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
29bf0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
29c00 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
29c10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
29c20 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
29c30 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
29c40 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
29c50 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
29c60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
29c70 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
29c80 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
29c90 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
29ca0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
29cb0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
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 63 68 61 72 20 2a 73 71 6c 69 74  onst char *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 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
29d10 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
29d20 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
29d30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29d40 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
29d50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
29d60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29d70 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
29d80 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
29d90 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
29da0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
29db0 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
29dc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
29dd0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
29de0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
29df0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
29e00 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
29e10 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
29e20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
29e30 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
29e40 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
29e50 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
29e60 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
29e70 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
29e80 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
29e90 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
29ea0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
29eb0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
29ec0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
29ed0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
29ee0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
29ef0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
29f00 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
29f10 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
29f20 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
29f30 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
29f40 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
29f50 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
29f60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
29f70 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
29f80 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
29f90 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
29fa0 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
29fb0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
29fc0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
29fd0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
29fe0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
29ff0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2a000 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2a010 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2a020 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2a030 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2a040 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2a050 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2a060 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2a070 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2a080 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2a090 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2a0a0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2a0b0 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2a0c0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2a0d0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2a0e0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2a0f0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2a100 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2a110 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2a120 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2a130 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2a140 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2a150 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2a160 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2a170 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2a180 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2a190 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2a1a0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2a1b0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2a1c0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2a1d0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2a1e0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2a1f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2a200 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a210 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2a220 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2a230 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2a240 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2a250 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2a260 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2a270 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2a280 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2a290 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2a2a0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
2a2b0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2a2c0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2a2d0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2a2e0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2a2f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2a300 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2a310 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2a320 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2a330 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2a340 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a350 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2a360 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2a370 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2a380 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2a390 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2a3a0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2a3b0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2a3c0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2a3d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2a3e0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2a3f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2a400 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2a410 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2a420 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2a430 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2a440 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2a450 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a460 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2a470 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a480 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2a490 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2a4a0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2a4b0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2a4c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2a4d0 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2a4e0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2a4f0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2a500 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2a510 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2a520 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2a530 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2a540 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2a550 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2a560 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2a570 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2a580 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2a590 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2a5a0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2a5b0 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2a5c0 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2a5d0 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2a5e0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2a5f0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2a600 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2a610 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2a620 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2a630 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2a640 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2a650 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2a660 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2a670 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2a680 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2a690 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2a6a0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2a6b0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2a6c0 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2a6d0 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2a6e0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2a6f0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2a700 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2a710 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2a720 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2a730 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2a740 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2a750 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2a760 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2a770 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2a780 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2a790 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2a7a0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2a7b0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2a7c0 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2a7d0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2a7e0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2a7f0 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2a800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2a810 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2a820 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2a830 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2a840 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2a850 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2a860 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2a870 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2a880 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2a890 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2a8a0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2a8b0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2a8c0 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2a8d0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2a8e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2a8f0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2a900 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2a910 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2a920 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2a930 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2a940 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2a950 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2a960 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2a970 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2a980 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2a990 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2a9a0 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2a9b0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2a9c0 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2a9d0 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2a9e0 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2a9f0 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2aa00 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2aa10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2aa20 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2aa30 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2aa40 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2aa50 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2aa60 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2aa70 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2aa80 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2aa90 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2aaa0 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2aab0 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2aac0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2aad0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2aae0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2aaf0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2ab00 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2ab10 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2ab20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2ab30 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2ab40 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2ab50 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2ab60 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2ab70 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2ab80 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2ab90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2aba0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2abb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2abc0 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2abd0 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2abe0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2abf0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2ac00 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2ac10 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2ac20 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2ac30 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2ac40 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2ac50 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2ac60 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2ac70 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2ac80 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2ac90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aca0 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2acb0 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2acc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2acd0 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2ace0 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2acf0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2ad00 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2ad10 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2ad20 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2ad30 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2ad40 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2ad50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ad60 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2ad70 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2ad80 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2ad90 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2ada0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2adb0 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2adc0 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2add0 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2ade0 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2adf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2ae00 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2ae10 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2ae20 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2ae30 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2ae40 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2ae50 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2ae60 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2ae70 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2ae80 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2ae90 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2aea0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2aeb0 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2aec0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2aed0 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2aee0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2aef0 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2af00 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2af10 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2af20 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2af30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2af40 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2af50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2af60 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2af70 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2af80 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2af90 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2afa0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2afb0 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2afc0 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2afd0 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2afe0 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2aff0 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2b000 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2b010 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2b020 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2b030 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2b040 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2b050 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2b060 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2b070 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2b080 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2b090 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2b0a0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2b0b0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2b0c0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2b0d0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2b0e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2b0f0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2b100 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2b110 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2b120 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2b130 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2b140 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2b150 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2b160 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2b170 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2b180 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b190 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2b1a0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2b1b0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2b1c0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2b1d0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2b1e0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2b1f0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2b200 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2b210 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2b220 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2b230 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2b240 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2b250 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2b260 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2b270 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2b280 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2b290 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2b2a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b2b0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2b2c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2b2d0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2b2e0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2b2f0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2b300 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2b310 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2b320 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2b330 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2b340 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2b350 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2b360 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2b370 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2b380 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2b390 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2b3a0 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
2b3b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b3c0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
2b3d0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2b3e0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
2b3f0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
2b400 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
2b410 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2b420 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
2b430 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2b440 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2b450 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
2b460 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2b470 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
2b480 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b490 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
2b4a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2b4b0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
2b4c0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
2b4d0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
2b4e0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
2b4f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
2b500 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
2b510 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
2b520 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
2b530 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2b540 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
2b550 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2b560 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2b570 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
2b580 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
2b590 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
2b5a0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2b5b0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2b5c0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
2b5d0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2b5e0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2b5f0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2b600 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2b610 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2b620 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
2b630 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
2b640 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
2b650 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2b660 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2b670 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
2b680 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
2b690 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
2b6a0 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
2b6b0 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
2b6c0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
2b6d0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
2b6e0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
2b6f0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
2b700 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
2b710 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
2b720 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b730 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
2b740 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
2b750 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2b760 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2b770 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b780 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b790 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2b7a0 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2b7b0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2b7c0 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2b7d0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2b7e0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2b7f0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2b800 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2b810 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2b820 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2b830 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2b840 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2b850 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2b860 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2b870 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2b880 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2b890 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2b8a0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2b8b0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2b8c0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2b8d0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2b8e0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2b8f0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2b900 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2b910 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2b920 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2b930 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2b940 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2b950 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2b960 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2b970 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2b980 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2b990 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2b9a0 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2b9b0 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2b9c0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2b9d0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2b9e0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2b9f0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2ba00 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2ba10 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2ba20 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2ba30 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2ba40 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2ba50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2ba60 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2ba70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2ba80 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2ba90 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2baa0 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2bab0 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2bac0 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2bad0 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2bae0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2baf0 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2bb00 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2bb10 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2bb20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2bb30 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2bb40 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2bb50 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2bb60 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2bb70 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2bb80 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2bb90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2bba0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2bbb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2bbc0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2bbd0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2bbe0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2bbf0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2bc00 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2bc10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bc20 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2bc30 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2bc40 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2bc50 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2bc60 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2bc70 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2bc80 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2bc90 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2bca0 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2bcb0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2bcc0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2bcd0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2bce0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2bcf0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2bd00 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2bd10 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2bd20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2bd30 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2bd40 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2bd50 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2bd60 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2bd70 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2bd80 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2bd90 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2bda0 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2bdb0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2bdc0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2bdd0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2bde0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2bdf0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2be00 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2be10 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2be20 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2be30 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2be40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2be50 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2be60 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2be70 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2be80 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2be90 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2bea0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2beb0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2bec0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2bed0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2bee0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2bef0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2bf00 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2bf10 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2bf20 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2bf30 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2bf40 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2bf50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2bf60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2bf70 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2bf80 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2bf90 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2bfa0 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2bfb0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2bfc0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2bfd0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2bfe0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2bff0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2c000 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2c020 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2c030 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2c040 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2c050 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2c060 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2c070 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2c080 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2c090 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2c0a0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2c0b0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2c0c0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2c0d0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2c0e0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2c0f0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2c100 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2c110 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2c120 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2c130 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2c140 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2c150 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2c160 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2c170 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2c180 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2c190 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2c1a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2c1b0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c1c0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2c1d0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2c1e0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2c1f0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2c200 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2c210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c220 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2c230 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2c240 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2c250 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2c260 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2c270 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2c280 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c290 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2c2a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2c2b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2c2c0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2c2d0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2c2e0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2c2f0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2c300 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c310 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2c320 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2c330 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2c340 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2c350 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2c360 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2c370 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2c380 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2c390 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2c3a0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2c3b0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2c3c0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2c3d0 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2c3e0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2c3f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2c400 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2c410 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2c420 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2c430 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2c440 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2c450 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2c460 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2c470 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2c480 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2c490 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2c4a0 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2c4b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2c4c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2c4d0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2c4e0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2c4f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2c500 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2c510 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2c520 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2c530 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2c540 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2c550 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2c560 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2c570 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2c580 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2c590 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2c5a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c5b0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2c5c0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2c5d0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2c5e0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2c5f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2c600 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2c610 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c620 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2c630 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2c640 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2c650 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c660 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2c670 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2c680 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2c690 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2c6a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2c6b0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2c6c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2c6d0 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2c6e0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2c6f0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2c700 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2c710 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2c720 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2c730 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2c740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c750 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2c760 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c770 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2c780 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2c790 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2c7a0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2c7b0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2c7c0 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2c7d0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2c7e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2c7f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c800 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2c810 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2c820 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2c830 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2c840 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2c850 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2c860 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2c870 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2c880 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2c890 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2c8a0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2c8b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2c8c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2c8d0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2c8e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c8f0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2c900 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c910 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c920 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2c930 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2c940 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2c950 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2c960 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2c970 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2c980 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c990 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2c9a0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2c9b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2c9c0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2c9d0 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2c9e0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2c9f0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2ca00 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ca10 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2ca20 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2ca30 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2ca40 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2ca50 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2ca60 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2ca70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2ca80 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2ca90 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2caa0 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2cab0 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2cac0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2cad0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2cae0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2caf0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2cb00 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2cb10 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2cb20 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2cb30 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2cb40 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2cb50 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2cb60 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2cb70 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2cb80 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2cb90 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2cba0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2cbb0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2cbc0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2cbd0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2cbe0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2cbf0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2cc00 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2cc10 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2cc20 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2cc30 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2cc40 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2cc50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2cc60 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2cc70 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2cc80 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2cc90 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2cca0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2ccb0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2ccc0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2ccd0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2cce0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2ccf0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2cd00 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2cd10 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2cd20 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2cd30 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2cd40 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2cd50 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2cd60 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2cd70 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2cd80 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2cd90 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2cda0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2cdb0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2cdc0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2cdd0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2cde0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2cdf0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2ce00 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
2ce10 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
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 54 45 58 54 20 20 20 20   <td>   TEXT    
2ce40 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2ce50 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2ce60 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2ce70 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2ce80 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2ce90 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
2cea0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2ceb0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2cec0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
2ced0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2cee0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2cef0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
2cf00 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2cf10 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2cf20 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2cf30 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2cf40 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2cf50 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2cf60 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2cf70 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
2cf80 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2cf90 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2cfa0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2cfb0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2cfc0 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
2cfd0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2cfe0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2cff0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2d000 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2d010 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2d020 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2d030 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2d040 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2d050 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2d060 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2d070 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2d080 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2d090 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2d0a0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2d0b0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2d0c0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2d0d0 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2d0e0 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2d0f0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2d100 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2d110 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2d120 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2d130 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2d140 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2d150 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2d160 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2d170 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2d180 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2d190 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2d1a0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2d1b0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2d1c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2d1d0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2d1e0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2d1f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2d200 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2d210 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2d220 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2d230 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2d240 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2d250 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2d260 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2d270 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2d280 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2d290 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2d2a0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2d2b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2d2c0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2d2d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d2e0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2d2f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2d300 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2d310 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2d320 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2d330 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2d340 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2d350 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2d360 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2d370 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2d380 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2d390 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2d3a0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2d3b0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2d3c0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2d3d0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2d3e0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2d3f0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2d400 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2d410 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d420 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2d430 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d440 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2d450 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2d460 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2d470 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2d480 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2d490 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2d4a0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2d4b0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2d4c0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2d4d0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2d4e0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2d4f0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2d500 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2d510 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2d520 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2d530 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2d540 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2d550 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2d560 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2d570 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2d580 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2d590 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2d5a0 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2d5b0 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2d5c0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2d5d0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2d5e0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2d5f0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2d600 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2d610 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2d620 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2d630 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2d640 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2d650 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2d660 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2d670 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2d680 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2d690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
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 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2d6f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2d700 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2d710 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2d720 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2d730 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2d740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d750 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2d760 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2d770 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2d780 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2d790 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2d7a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2d7b0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2d7c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d7d0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2d7e0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2d7f0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2d800 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2d810 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2d820 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2d830 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2d840 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2d850 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2d860 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2d870 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2d880 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2d890 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2d8a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2d8b0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2d8c0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2d8d0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2d8e0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2d8f0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2d900 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2d910 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2d920 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d930 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2d940 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2d950 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2d960 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2d970 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2d980 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2d990 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2d9a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d9b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2d9c0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2d9d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2d9e0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2d9f0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2da00 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2da10 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2da20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2da30 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2da40 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2da50 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2da60 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2da70 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2da80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2da90 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2daa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2dab0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2dac0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2dad0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2dae0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2daf0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2db00 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2db10 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2db20 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2db30 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2db40 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2db50 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2db60 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2db70 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2db80 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2db90 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2dba0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2dbb0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2dbc0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2dbd0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2dbe0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2dbf0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2dc00 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2dc10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2dc20 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2dc30 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2dc40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2dc50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2dc60 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2dc70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2dc80 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2dc90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2dca0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2dcb0 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2dcc0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2dcd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2dce0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2dcf0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2dd00 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2dd10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2dd20 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
2dd30 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2dd40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2dd50 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2dd60 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2dd70 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
2dd80 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2dd90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2dda0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ddb0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2ddc0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2ddd0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2dde0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2ddf0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2de00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2de10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2de20 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2de30 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2de40 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2de50 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2de60 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2de70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2de80 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2de90 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2dea0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2deb0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2dec0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2ded0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2dee0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2def0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2df00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2df10 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2df20 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2df30 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2df40 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2df50 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
2df60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2df70 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
2df80 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
2df90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2dfa0 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
2dfb0 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
2dfc0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2dfd0 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
2dfe0 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
2dff0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
2e000 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
2e010 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
2e020 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2e030 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
2e040 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2e050 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2e060 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
2e070 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2e080 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2e090 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
2e0a0 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
2e0b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
2e0c0 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
2e0d0 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
2e0e0 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
2e0f0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
2e100 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2e110 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
2e120 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
2e130 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2e140 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
2e150 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2e160 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2e170 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
2e180 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
2e190 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
2e1a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
2e1b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2e1c0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2e1d0 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
2e1e0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
2e1f0 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
2e200 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e210 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
2e220 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
2e230 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
2e240 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
2e250 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2e260 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
2e270 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
2e280 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2e290 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2e2a0 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
2e2b0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
2e2c0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
2e2d0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
2e2e0 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
2e2f0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
2e300 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
2e310 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
2e320 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
2e330 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
2e340 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
2e350 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e   int sqlite3_fin
2e360 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
2e370 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2e380 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2e390 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
2e3a0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2e3b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2e3c0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
2e3d0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
2e3e0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
2e3f0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2e400 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
2e410 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
2e420 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
2e430 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
2e440 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
2e450 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
2e460 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
2e470 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
2e480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2e490 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2e4a0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
2e4b0 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
2e4c0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
2e4d0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2e4e0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
2e4f0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
2e500 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2e510 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2e520 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
2e530 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e540 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
2e550 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
2e560 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
2e570 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2e580 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2e590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2e5a0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2e5b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e5c0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2e5d0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
2e5e0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
2e5f0 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
2e600 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
2e610 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
2e620 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
2e630 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
2e640 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2e650 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
2e660 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2e670 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2e680 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2e690 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2e6a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e6b0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
2e6c0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
2e6d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2e6e0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2e6f0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2e700 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2e710 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2e720 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
2e730 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2e740 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
2e750 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
2e760 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
2e770 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
2e780 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
2e790 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2e7a0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
2e7b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2e7c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2e7d0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
2e7e0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
2e7f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
2e800 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
2e810 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2e820 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2e830 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e840 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2e850 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2e860 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e870 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2e880 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
2e890 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2e8a0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2e8b0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2e8c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2e8d0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2e8e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2e8f0 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2e900 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2e910 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2e920 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2e930 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2e940 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2e950 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
2e960 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
2e970 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
2e980 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
2e990 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
2e9a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2e9b0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
2e9c0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
2e9d0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
2e9e0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
2e9f0 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
2ea00 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2ea10 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
2ea20 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2ea30 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2ea40 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2ea50 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
2ea60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2ea70 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
2ea80 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
2ea90 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
2eaa0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2eab0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
2eac0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
2ead0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
2eae0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2eaf0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2eb00 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
2eb10 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
2eb20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
2eb30 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
2eb40 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2eb50 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2eb60 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
2eb70 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
2eb80 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
2eb90 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
2eba0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2ebb0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2ebc0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
2ebd0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
2ebe0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
2ebf0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2ec00 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
2ec10 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
2ec20 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
2ec30 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
2ec40 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
2ec50 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
2ec60 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
2ec70 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
2ec80 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
2ec90 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
2eca0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
2ecb0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
2ecc0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2ecd0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
2ece0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
2ecf0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2ed00 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
2ed10 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2ed20 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2ed30 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
2ed40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
2ed50 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
2ed60 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2ed70 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
2ed80 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
2ed90 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
2eda0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
2edb0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
2edc0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2edd0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2ede0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
2edf0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
2ee00 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
2ee10 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2ee20 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
2ee30 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
2ee40 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2ee50 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
2ee60 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
2ee70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
2ee80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2ee90 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
2eea0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
2eeb0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
2eec0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
2eed0 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75  s.  Every SQL fu
2eee0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2eef0 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62  ation must be ab
2ef00 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  le to work.** wi
2ef10 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
2ef20 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
2ef30 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
2ef40 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
2ef50 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
2ef60 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
2ef70 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
2ef80 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61  er.  ^An applica
2ef90 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
2efa0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2efb0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
2efc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2efd0 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
2efe0 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
2eff0 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
2f000 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
2f010 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
2f020 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e  f eTextRep..** ^
2f030 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2f040 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2f050 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2f060 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2f070 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2f080 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2f090 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2f0a0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2f0b0 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2f0c0 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2f0d0 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2f0e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2f0f0 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2f100 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2f110 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2f120 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2f130 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2f140 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2f150 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
2f160 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2f170 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2f180 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2f190 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2f1a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2f1b0 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2f1c0 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2f1d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2f1e0 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
2f1f0 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
2f200 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
2f210 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2f220 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2f230 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2f240 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2f250 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2f260 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2f270 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2f280 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
2f290 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
2f2a0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2f2b0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2f2c0 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
2f2d0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
2f2e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
2f2f0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2f300 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
2f310 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2f320 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
2f330 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
2f340 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2f350 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
2f360 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
2f370 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
2f380 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
2f390 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
2f3a0 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
2f3b0 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
2f3c0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
2f3d0 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
2f3e0 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
2f3f0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
2f400 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
2f410 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
2f420 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f430 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f440 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
2f450 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
2f460 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
2f470 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
2f480 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
2f490 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
2f4a0 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
2f4b0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
2f4c0 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
2f4d0 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
2f4e0 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
2f4f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2f500 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
2f510 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
2f520 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
2f530 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
2f540 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2f550 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f560 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
2f570 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
2f580 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
2f590 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
2f5a0 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
2f5b0 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
2f5c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
2f5d0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
2f5e0 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
2f5f0 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
2f600 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
2f610 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
2f620 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2f630 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2f640 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
2f650 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2f660 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
2f670 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f680 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
2f690 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
2f6a0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
2f6b0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
2f6c0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
2f6d0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
2f6e0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
2f6f0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2f700 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
2f710 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
2f720 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
2f730 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
2f740 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
2f750 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
2f760 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2f770 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
2f780 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2f790 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
2f7a0 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
2f7b0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
2f7c0 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
2f7d0 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
2f7e0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
2f7f0 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
2f800 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
2f810 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
2f820 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2f830 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
2f840 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
2f850 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
2f860 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
2f870 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2f880 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
2f890 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
2f8a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2f8b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2f8c0 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
2f8d0 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
2f8e0 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
2f8f0 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
2f900 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2f910 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2f920 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
2f930 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
2f940 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
2f950 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
2f960 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
2f970 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
2f980 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f990 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
2f9a0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
2f9b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2f9c0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2f9d0 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
2f9e0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
2f9f0 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
2fa00 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
2fa10 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
2fa20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2fa30 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
2fa40 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2fa50 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2fa60 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
2fa70 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2fa80 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
2fa90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2faa0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
2fab0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2fac0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
2fad0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2fae0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2faf0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2fb00 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2fb10 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2fb20 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2fb30 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2fb40 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2fb50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2fb60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2fb70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2fb80 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2fb90 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
2fba0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2fbb0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2fbc0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2fbd0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2fbe0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2fbf0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2fc00 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2fc10 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2fc20 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2fc30 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2fc40 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2fc50 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2fc60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fc70 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2fc80 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2fc90 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2fca0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
2fcb0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2fcc0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2fcd0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
2fce0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2fcf0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2fd00 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2fd10 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2fd20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2fd30 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2fd40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2fd50 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2fd60 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2fd70 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2fd80 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2fd90 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2fda0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2fdb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
2fdc0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
2fdd0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
2fde0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2fdf0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
2fe00 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
2fe10 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
2fe20 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
2fe30 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
2fe40 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
2fe50 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
2fe60 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
2fe70 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
2fe80 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2fe90 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
2fea0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2feb0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
2fec0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2fed0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
2fee0 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
2fef0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
2ff00 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
2ff10 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
2ff20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
2ff30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ff40 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
2ff50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2ff60 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
2ff70 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2ff80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
2ff90 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
2ffa0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
2ffb0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
2ffc0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
2ffd0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2ffe0 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
2fff0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
30000 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
30010 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
30020 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
30030 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
30040 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
30050 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
30060 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
30070 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
30080 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
30090 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
300a0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
300b0 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
300c0 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
300d0 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
300e0 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
300f0 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
30100 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
30110 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
30120 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
30130 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  ED.SQLITE_API SQ
30140 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
30150 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
30160 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
30170 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
30180 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
30190 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
301a0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
301b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
301c0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
301d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
301e0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
301f0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
30200 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
30210 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
30220 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
30230 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
30240 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
30250 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
30260 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
30270 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
30280 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
30290 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
302a0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
302b0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
302c0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
302d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
302e0 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
302f0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
30300 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
30310 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
30320 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
30330 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
30340 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
30350 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
30360 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
30370 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30380 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
30390 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
303a0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
303b0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
303c0 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
303d0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
303e0 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
303f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
30400 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
30410 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
30420 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
30430 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
30440 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
30450 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
30460 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30470 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
30480 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30490 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
304a0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
304b0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
304c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
304d0 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
304e0 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
304f0 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
30500 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
30510 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
30520 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
30530 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30540 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
30550 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
30560 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
30570 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
30580 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
30590 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
305a0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
305b0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
305c0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
305d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
305e0 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
305f0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
30600 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
30610 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30620 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
30630 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
30640 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
30650 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
30660 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30670 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
30680 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
30690 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
306a0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
306b0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
306c0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
306d0 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
306e0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
306f0 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
30700 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
30710 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
30720 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30730 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
30740 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
30750 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
30760 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
30770 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
30780 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
30790 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
307a0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
307b0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
307c0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
307d0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
307e0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
307f0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
30800 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
30810 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
30820 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
30830 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
30840 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
30850 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
30860 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
30870 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
30880 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
30890 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
308a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
308b0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
308c0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
308d0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
308e0 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
308f0 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
30900 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
30910 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
30920 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
30930 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
30940 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
30950 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
30960 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
30970 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
30980 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
30990 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
309a0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
309b0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
309c0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
309d0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
309e0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
309f0 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
30a00 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
30a10 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
30a20 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
30a30 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
30a40 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
30a50 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
30a60 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
30a70 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
30a80 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
30a90 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
30aa0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
30ab0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
30ac0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
30ad0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
30ae0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
30af0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30b00 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
30b10 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
30b20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
30b30 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
30b40 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
30b50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30b60 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
30b70 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
30b80 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
30b90 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
30ba0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
30bb0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
30bc0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
30bd0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
30be0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
30bf0 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
30c00 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
30c10 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
30c20 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
30c30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
30c40 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
30c50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30c60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30c70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
30c80 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
30c90 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
30ca0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
30cb0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
30cc0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
30cd0 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
30ce0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
30cf0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
30d00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
30d10 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
30d20 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
30d30 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
30d40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
30d50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
30d60 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
30d70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
30d80 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
30d90 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
30da0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
30db0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
30dc0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
30dd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30de0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
30df0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
30e00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
30e10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
30e20 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
30e30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
30e40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
30e50 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
30e60 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30e70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
30e80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
30e90 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
30ea0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
30eb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
30ec0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
30ed0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
30ee0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30ef0 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
30f00 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
30f10 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
30f20 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
30f30 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
30f40 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
30f50 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
30f60 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
30f70 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
30f80 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
30f90 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
30fa0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30fb0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
30fc0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
30fd0 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
30fe0 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
30ff0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
31000 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
31010 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
31020 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
31030 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
31040 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
31050 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
31060 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
31070 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
31080 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
31090 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
310a0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
310b0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
310c0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
310d0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
310e0 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
310f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31100 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
31110 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
31120 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
31130 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
31140 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
31150 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
31160 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
31170 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
31180 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
31190 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
311a0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
311b0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
311c0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
311d0 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
311e0 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
311f0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
31200 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
31210 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
31220 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
31230 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
31240 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31250 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
31260 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
31270 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
31280 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
31290 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
312a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
312b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
312c0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
312d0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
312e0 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
312f0 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
31300 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
31310 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
31320 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
31330 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
31340 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
31350 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
31360 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
31370 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31380 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
31390 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
313a0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
313b0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
313c0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
313d0 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
313e0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
313f0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
31400 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31410 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
31420 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
31430 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
31440 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
31450 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
31460 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
31470 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
31480 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
31490 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
314a0 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
314b0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
314c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
314d0 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
314e0 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
314f0 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
31500 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
31510 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
31520 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
31530 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
31540 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
31550 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31560 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
31570 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
31580 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
31590 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
315a0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
315b0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
315c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
315d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
315e0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
315f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
31600 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
31610 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
31620 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
31630 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
31640 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
31650 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
31660 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
31670 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
31680 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
31690 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
316a0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
316b0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
316c0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
316d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61   void *sqlite3_a
316e0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
316f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31700 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
31710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31720 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
31730 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
31740 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
31750 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
31760 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
31770 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
31780 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
31790 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
317a0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
317b0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
317c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
317d0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
317e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
317f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31800 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
31810 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
31820 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
31830 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
31840 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
31850 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
31860 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
31870 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
31880 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
31890 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
318a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
318b0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
318c0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
318d0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
318e0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
318f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
31900 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
31910 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
31920 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
31930 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
31940 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
31950 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
31960 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
31970 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
31980 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31990 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
319a0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
319b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
319c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
319d0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
319e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
319f0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
31a00 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
31a10 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
31a20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
31a30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
31a40 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
31a50 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
31a60 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
31a70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31a80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31a90 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
31aa0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
31ab0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
31ac0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
31ad0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
31ae0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
31af0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
31b00 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
31b10 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
31b20 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
31b30 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
31b40 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
31b50 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
31b60 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
31b70 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
31b80 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
31b90 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
31ba0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
31bb0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
31bc0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
31bd0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
31be0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
31bf0 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
31c00 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
31c10 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
31c20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
31c30 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
31c40 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
31c50 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
31c60 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
31c70 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
31c80 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
31c90 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
31ca0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
31cb0 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
31cc0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
31cd0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
31ce0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
31cf0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
31d00 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
31d10 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
31d20 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
31d30 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
31d40 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
31d50 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
31d60 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
31d70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
31d80 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
31d90 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
31da0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
31db0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
31dc0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
31dd0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
31de0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
31df0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
31e00 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
31e10 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
31e20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31e30 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
31e40 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
31e50 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
31e60 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
31e70 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
31e80 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
31e90 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
31ea0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
31eb0 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
31ec0 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
31ed0 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
31ee0 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
31ef0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
31f00 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
31f10 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
31f20 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
31f30 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
31f40 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
31f50 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
31f60 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
31f70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
31f80 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
31f90 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
31fa0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
31fb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31fc0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
31fd0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
31fe0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
31ff0 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
32000 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
32010 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
32020 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
32030 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
32040 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
32050 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
32060 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
32070 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
32080 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
32090 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
320a0 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
320b0 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
320c0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
320d0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
320e0 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
320f0 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
32100 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
32110 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
32120 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
32130 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
32140 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
32150 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
32160 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
32170 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
32180 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
32190 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
321a0 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
321b0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
321c0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
321d0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
321e0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
321f0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
32200 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
32210 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
32220 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
32230 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
32240 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
32250 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
32260 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
32270 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
32280 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
32290 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
322a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
322b0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
322c0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
322d0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
322e0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
322f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
32300 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
32310 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
32320 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
32330 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32340 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
32350 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32360 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
32370 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32380 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
32390 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
323a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
323b0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
323c0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
323d0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
323e0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
323f0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
32400 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
32410 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
32420 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
32430 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
32440 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
32450 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
32460 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
32470 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
32480 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
32490 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
324a0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
324b0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
324c0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
324d0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
324e0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
324f0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
32500 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
32510 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
32520 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
32530 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
32540 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
32550 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
32560 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
32570 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
32580 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
32590 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
325a0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
325b0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
325c0 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
325d0 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
325e0 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
325f0 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
32600 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
32610 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
32620 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
32630 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
32640 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
32650 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
32660 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
32670 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
32680 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
32690 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
326a0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
326b0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
326c0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
326d0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
326e0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
326f0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
32700 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
32710 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
32720 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
32730 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
32740 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
32750 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
32760 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
32770 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32780 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
32790 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
327a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
327b0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
327c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
327d0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
327e0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
327f0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
32800 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
32810 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
32820 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
32830 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
32840 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
32850 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
32860 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
32870 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
32880 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
32890 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
328a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
328b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
328c0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
328d0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
328e0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
328f0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
32900 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32910 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
32920 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
32930 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
32940 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
32950 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
32960 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
32970 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
32980 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
32990 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
329a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
329b0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
329c0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
329d0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
329e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
329f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
32a00 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
32a10 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
32a20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
32a30 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
32a40 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
32a50 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
32a60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
32a70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32a80 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
32a90 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
32aa0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
32ab0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32ac0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32ad0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
32ae0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
32af0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
32b00 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
32b10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
32b20 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
32b30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32b40 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
32b50 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
32b60 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
32b70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
32b80 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
32b90 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
32ba0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
32bb0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
32bc0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
32bd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32be0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
32bf0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
32c00 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
32c10 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
32c20 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
32c30 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
32c40 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
32c50 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
32c60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32c70 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
32c80 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
32c90 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
32ca0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
32cb0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
32cc0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
32cd0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
32ce0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
32cf0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
32d00 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32d10 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
32d20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32d30 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
32d40 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
32d50 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
32d60 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
32d70 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
32d80 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
32d90 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
32da0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
32db0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
32dc0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
32dd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32de0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
32df0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
32e00 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
32e10 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
32e20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
32e30 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
32e40 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
32e50 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
32e60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
32e70 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
32e80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32e90 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
32ea0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
32eb0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
32ec0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
32ed0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
32ee0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
32ef0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
32f00 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
32f10 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
32f20 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
32f30 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
32f40 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
32f50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32f60 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
32f70 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
32f80 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
32f90 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
32fa0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
32fb0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
32fc0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
32fd0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
32fe0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
32ff0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
33000 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
33010 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
33020 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
33030 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
33040 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
33050 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
33060 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
33070 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33080 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33090 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
330a0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
330b0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
330c0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
330d0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
330e0 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
330f0 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
33100 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
33110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33120 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
33130 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
33140 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
33150 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
33160 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
33170 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
33180 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
33190 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
331a0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
331b0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
331c0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
331d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
331e0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
331f0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
33200 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
33210 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
33220 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
33230 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33240 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
33250 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
33260 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
33270 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
33280 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33290 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
332a0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
332b0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
332c0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
332d0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
332e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
332f0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
33300 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
33310 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
33320 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33330 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33340 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
33350 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33360 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
33370 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33380 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
33390 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
333a0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
333b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
333c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
333d0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
333e0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
333f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33400 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33410 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
33420 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
33430 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
33440 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
33450 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
33460 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
33470 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
33480 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
33490 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
334a0 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
334b0 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
334c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
334d0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
334e0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
334f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33500 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
33510 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
33520 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
33530 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33540 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
33550 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
33560 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
33570 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
33580 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
33590 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
335a0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
335b0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
335c0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
335d0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
335e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
335f0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
33600 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
33610 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
33620 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
33630 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
33640 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
33650 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
33660 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
33670 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33680 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
33690 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
336a0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
336b0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
336c0 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
336d0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
336e0 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
336f0 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
33700 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
33710 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
33720 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
33730 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
33740 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
33750 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
33760 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
33770 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
33780 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
33790 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
337a0 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
337b0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
337c0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
337d0 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
337e0 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
337f0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
33800 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
33810 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
33820 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
33830 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
33840 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
33850 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33860 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33870 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
33880 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
33890 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
338a0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
338b0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
338c0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
338d0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
338e0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
338f0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
33900 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
33910 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
33920 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
33930 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
33940 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
33950 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33960 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
33970 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
33980 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
33990 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
339a0 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
339b0 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
339c0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
339d0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
339e0 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
339f0 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
33a00 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
33a10 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
33a20 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
33a30 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
33a40 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
33a50 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
33a60 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
33a70 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
33a80 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
33a90 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
33aa0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
33ab0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
33ac0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
33ad0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
33ae0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
33af0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
33b00 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
33b10 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
33b20 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
33b30 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
33b40 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
33b50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
33b60 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
33b70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33b80 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
33b90 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
33ba0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
33bb0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
33bc0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33bd0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
33be0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
33bf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33c00 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
33c10 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
33c20 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
33c30 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
33c40 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
33c50 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
33c60 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
33c70 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
33c80 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
33c90 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
33ca0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
33cb0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
33cc0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
33cd0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
33ce0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
33cf0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
33d00 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
33d10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
33d20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
33d30 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
33d40 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
33d50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33d60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
33d70 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
33d80 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
33d90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33da0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
33db0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
33dc0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
33dd0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
33de0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
33df0 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
33e00 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
33e10 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
33e20 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
33e30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
33e40 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
33e50 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
33e60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
33e70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
33e80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
33e90 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
33ea0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
33eb0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
33ec0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33ed0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
33ee0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
33ef0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
33f00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
33f10 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
33f20 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
33f30 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
33f40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33f50 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
33f60 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
33f70 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  r*, int);.SQLITE
33f80 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
33f90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33fa0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33fb0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
33fc0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
33fd0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
33fe0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
33ff0 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
34000 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
34010 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34020 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
34030 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34040 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
34050 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34060 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
34070 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
34080 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
34090 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
340a0 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
340b0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
340c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
340d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
340e0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
340f0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
34100 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
34110 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34120 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
34130 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
34140 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34160 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
34170 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
34180 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
34190 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
341a0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
341b0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
341c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
341d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
341e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
341f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
34200 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34210 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
34220 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34230 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
34240 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
34250 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34260 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34270 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
34280 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
34290 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
342a0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
342b0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
342c0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
342d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
342e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
342f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
34300 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34310 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
34320 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
34330 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
34340 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
34350 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
34360 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ces.**.** ^These
34370 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
34380 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
34390 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
343a0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
343b0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
343c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
343d0 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
343e0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
343f0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
34400 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
34410 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
34420 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
34430 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34440 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
34450 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
34460 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
34470 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
34480 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
34490 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
344a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
344b0 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
344c0 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
344d0 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
344e0 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
344f0 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
34500 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
34510 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
34520 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
34530 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
34540 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
34550 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
34560 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
34570 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
34580 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
34590 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
345a0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
345b0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
345c0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
345d0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
345e0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
345f0 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
34600 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
34610 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
34620 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
34630 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
34640 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
34650 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34660 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
34670 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
34680 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
34690 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
346a0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
346b0 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
346c0 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
346d0 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
346e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
346f0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
34700 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
34710 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
34720 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
34730 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
34740 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
34750 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
34760 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
34770 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
34780 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
34790 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
347a0 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
347b0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
347c0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
347d0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
347e0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
347f0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
34800 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
34810 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
34820 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
34830 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
34840 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
34850 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
34860 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
34870 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
34880 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
34890 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
348a0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
348b0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
348c0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
348d0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
348e0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
348f0 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
34900 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
34910 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
34920 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
34930 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
34940 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
34950 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
34960 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
34970 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
34980 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
34990 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
349a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
349b0 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
349c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
349d0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
349e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
349f0 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
34a00 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
34a10 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
34a20 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
34a30 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
34a40 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
34a50 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
34a60 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
34a70 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
34a80 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
34a90 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
34aa0 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
34ab0 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
34ac0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
34ad0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
34ae0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
34af0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
34b00 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
34b10 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
34b20 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
34b30 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
34b40 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
34b50 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
34b60 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
34b70 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
34b80 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
34b90 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
34ba0 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
34bb0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
34bc0 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
34bd0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
34be0 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
34bf0 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
34c00 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
34c10 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
34c20 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
34c30 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
34c40 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
34c50 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
34c60 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
34c70 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
34c80 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
34c90 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
34ca0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
34cb0 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
34cc0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
34cd0 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
34ce0 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
34cf0 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
34d00 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
34d10 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
34d20 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
34d30 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
34d40 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34d50 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
34d60 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
34d70 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
34d80 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
34d90 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
34da0 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
34db0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
34dc0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
34dd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34de0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
34df0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
34e00 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
34e10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34e20 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
34e30 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
34e40 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
34e50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34e60 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
34e70 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
34e80 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
34e90 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
34ea0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
34eb0 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
34ec0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
34ed0 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
34ee0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
34ef0 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
34f00 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
34f10 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
34f20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34f30 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
34f40 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
34f50 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
34f60 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
34f70 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
34f80 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
34f90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34fa0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
34fb0 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
34fc0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
34fd0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
34fe0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34ff0 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
35000 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
35010 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
35020 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
35030 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
35040 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
35050 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
35060 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
35070 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
35080 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
35090 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
350a0 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
350b0 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
350c0 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
350d0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
350e0 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
350f0 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
35100 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
35110 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
35120 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
35130 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .** 
35140 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
35150 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
35160 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
35170 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
35180 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
35190 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
351a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
351b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
351c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
351d0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
351e0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
351f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
35200 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
35210 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
35220 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
35230 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
35240 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  void*).);.SQLITE
35250 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
35260 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35270 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
35280 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
35290 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
352a0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
352b0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
352c0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
352d0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
352e0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
352f0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
35300 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c  y)(void*).);.SQL
35310 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35320 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35330 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
35340 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
35350 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
35360 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
35370 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
35380 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
35390 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
353a0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
353b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
353c0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
353d0 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
353e0 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
353f0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
35400 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
35410 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
35420 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
35430 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
35440 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
35450 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
35460 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
35470 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
35480 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
35490 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
354a0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
354b0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
354c0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
354d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
354e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
354f0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
35500 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
35510 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
35520 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
35530 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
35540 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
35550 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
35560 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
35570 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
35580 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
35590 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
355a0 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
355b0 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
355c0 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
355d0 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
355e0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
355f0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
35600 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
35610 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
35620 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
35630 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
35640 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
35650 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
35660 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35670 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
35680 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
35690 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
356a0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
356b0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
356c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
356d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
356e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
356f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
35700 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
35710 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
35720 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
35730 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
35740 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
35750 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
35760 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
35770 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
35780 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
35790 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
357a0 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
357b0 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
357c0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
357d0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
357e0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
357f0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
35800 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
35810 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
35820 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
35830 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
35840 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
35850 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
35860 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
35870 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
35880 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
35890 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
358a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
358b0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  on_v2()]..*/.SQL
358c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
358d0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
358e0 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
358f0 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
35900 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
35910 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
35920 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
35930 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
35940 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
35950 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
35960 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
35970 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
35980 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
35990 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
359a0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
359b0 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
359c0 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
359d0 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
359e0 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
359f0 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
35a00 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
35a10 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
35a20 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
35a30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
35a40 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
35a50 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
35a60 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
35a70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
35a80 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
35a90 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
35aa0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
35ab0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
35ac0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
35ad0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
35ae0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
35af0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
35b00 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
35b10 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
35b20 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
35b30 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
35b40 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
35b50 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
35b60 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
35b70 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
35b80 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
35b90 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
35ba0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
35bb0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
35bc0 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
35bd0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
35be0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
35bf0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
35c00 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
35c10 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
35c20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
35c40 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
35c50 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
35c60 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
35c70 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
35c80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
35c90 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
35ca0 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
35cb0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
35cc0 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
35cd0 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
35ce0 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
35cf0 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
35d00 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
35d10 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
35d20 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
35d30 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35d40 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
35d50 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
35d60 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
35d70 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
35d80 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
35d90 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
35da0 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
35db0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
35dc0 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
35dd0 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
35de0 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
35df0 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
35e00 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
35e10 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
35e20 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rk..*/.SQLITE_AP
35e30 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  I void sqlite3_a
35e40 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
35e50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
35e60 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
35e70 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
35e80 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
35e90 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
35ea0 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
35eb0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
35ec0 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
35ed0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
35ee0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
35ef0 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
35f00 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
35f10 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
35f20 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
35f30 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
35f40 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
35f50 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
35f60 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
35f70 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
35f80 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
35f90 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
35fa0 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
35fb0 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
35fc0 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
35fd0 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
35fe0 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
35ff0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
36000 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
36010 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
36020 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
36030 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
36040 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
36050 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
36060 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
36070 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
36080 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
36090 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
360a0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
360b0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
360c0 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
360d0 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
360e0 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
360f0 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
36100 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
36110 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
36120 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
36130 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
36140 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
36150 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
36160 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
36170 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
36180 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
36190 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c  ragraphs..*/.SQL
361a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
361b0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
361c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
361d0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
361e0 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
361f0 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
36200 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
36210 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
36220 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
36230 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
36240 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
36250 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
36260 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
36270 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
36280 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
36290 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
362a0 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
362b0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
362c0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
362d0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
362e0 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
362f0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
36300 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
36310 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
36320 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
36330 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
36340 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
36350 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
36360 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
36370 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
36380 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
36390 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
363a0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
363b0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
363c0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
363d0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
363e0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
363f0 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
36400 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
36410 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
36420 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
36430 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
36440 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
36450 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
36460 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
36470 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
36480 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
36490 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
364a0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
364b0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
364c0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
364d0 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
364e0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
364f0 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
36500 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
36510 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
36520 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
36530 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
36540 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
36550 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
36560 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
36570 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
36580 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
36590 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
365a0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
365b0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
365c0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
365d0 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
365e0 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
365f0 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
36600 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
36610 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
36620 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
36630 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
36640 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
36650 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
36660 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
36670 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
36680 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
36690 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
366a0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
366b0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
366c0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
366d0 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
366e0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
366f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36700 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
36710 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
36720 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
36730 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
36740 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
36750 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a  e avoided..**.**
36760 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
36770 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
36780 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
36790 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
367a0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
367b0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
367c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
367d0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
367e0 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
367f0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
36800 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
36810 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
36820 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
36830 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
36840 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
36850 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
36860 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
36870 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
36880 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
36890 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
368a0 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
368b0 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
368c0 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
368d0 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
368e0 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
368f0 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
36900 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
36910 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
36920 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
36930 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
36940 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
36950 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
36960 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
36970 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
36980 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
36990 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
369a0 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
369b0 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
369c0 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
369d0 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
369e0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
369f0 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
36a00 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
36a10 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te>.*/.SQLITE_AP
36a20 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
36a30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
36a40 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
36a50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
36a60 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
36a70 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61  r Holding Databa
36a80 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
36a90 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
36aa0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
36ab0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
36ac0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
36ad0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
36ae0 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
36af0 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
36b00 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
36b10 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  es.** specified 
36b20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
36b30 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65  pathname and cre
36b40 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64  ated or accessed
36b50 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68   by.** SQLite wh
36b60 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
36b70 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c  -in windows [sql
36b80 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20  ite3_vfs | VFS] 
36b90 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a  will be assumed.
36ba0 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76  ** to be relativ
36bb0 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74  e to that direct
36bc0 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20  ory.)^ ^If this 
36bd0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
36be0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74  LL.** pointer, t
36bf0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
36c00 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61  es that all data
36c10 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69  base files speci
36c20 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72  fied.** with a r
36c30 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
36c40 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f   are relative to
36c50 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
36c60 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68  ectory.** for th
36c70 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79  e process.  Only
36c80 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
36c90 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68   makes use of th
36ca0 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72  is global.** var
36cb0 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e  iable; it is ign
36cc0 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78  ored by the unix
36cd0 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e   VFS..**.** Chan
36ce0 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f  ging the value o
36cf0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
36d00 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65  while a database
36d10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a   connection is.*
36d20 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c  * open can resul
36d30 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64  t in a corrupt d
36d40 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49  atabase..**.** I
36d50 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
36d60 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
36d70 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
36d80 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
36d90 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
36da0 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
36db0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
36dc0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
36dd0 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
36de0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36df0 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
36e00 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
36e10 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
36e20 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
36e30 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
36e40 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
36e50 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
36e60 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
36e70 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
36e80 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
36e90 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
36ea0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
36eb0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
36ec0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
36ed0 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
36ee0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
36ef0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
36f00 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
36f10 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
36f20 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
36f30 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
36f40 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
36f50 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
36f60 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
36f70 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
36f80 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
36f90 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
36fa0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
36fb0 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
36fc0 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
36fd0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
36fe0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
36ff0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
37000 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
37010 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
37020 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
37030 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
37040 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
37050 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
37060 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
37070 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
37080 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
37090 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
370a0 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
370b0 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
370c0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
370d0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
370e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
370f0 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
37100 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
37110 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
37120 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
37130 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
37140 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
37150 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
37160 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64   *sqlite3_data_d
37170 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
37180 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
37190 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20  For Auto-Commit 
371a0 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  Mode.** KEYWORDS
371b0 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
371c0 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  de}.**.** ^The s
371d0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
371e0 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
371f0 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
37200 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
37210 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
37220 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
37230 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
37240 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
37250 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
37260 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f    ^Autocommit mo
37270 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
37280 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ult..** ^Autocom
37290 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
372a0 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
372b0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
372c0 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
372d0 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
372e0 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
372f0 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
37300 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
37310 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
37320 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
37330 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
37340 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
37350 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72  ansaction (error
37360 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
37370 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
37380 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53  TE_IOERR],.** [S
37390 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
373a0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
373b0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
373c0 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
373d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
373e0 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
373f0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
37400 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74    The only way t
37410 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68  o.** find out wh
37420 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74  ether SQLite aut
37430 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
37440 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  d back the trans
37450 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20  action after.** 
37460 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75  an error is to u
37470 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  se this function
37480 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
37490 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
374a0 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
374b0 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
374c0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
374d0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73  ction while this
374e0 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
374f0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
37500 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73  turn value.** is
37510 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
37520 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
37530 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
37540 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
37550 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37560 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
37570 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
37580 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
37590 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
375a0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
375b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
375c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
375d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
375e0 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20  e.** to which a 
375f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37600 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e  ent] belongs.  ^
37610 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
37620 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74  nnection].** ret
37630 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
37640 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
37650 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
37660 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
37670 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72  that was the fir
37680 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
37690 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  o the [sqlite3_p
376a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c  repare_v2()] cal
376b0 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e  l (or its varian
376c0 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65  ts) that was use
376d0 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74  d to.** create t
376e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  he statement in 
376f0 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
37700 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
37710 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
37720 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
37730 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
37740 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72   CAPI3REF: Retur
37750 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46  n The Filename F
37760 6f 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  or A Database Co
37770 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
37780 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66  The sqlite3_db_f
37790 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74  ilename(D,N) int
377a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
377b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69   pointer to a fi
377c0 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69  lename.** associ
377d0 61 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61  ated with databa
377e0 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69  se N of connecti
377f0 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e  on D.  ^The main
37800 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
37810 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22  * has the name "
37820 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65  main".  If there
37830 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20   is no attached 
37840 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68  database N on th
37850 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
37860 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69  nnection D, or i
37870 66 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20  f database N is 
37880 61 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69  a temporary or i
37890 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
378a0 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c  e, then.** a NUL
378b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
378c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
378d0 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72  e filename retur
378e0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
378f0 74 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70  tion is the outp
37900 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75  ut of the.** xFu
37910 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f  llPathname metho
37920 64 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20  d of the [VFS]. 
37930 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   ^In other words
37940 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  , the filename.*
37950 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73  * will be an abs
37960 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20  olute pathname, 
37970 65 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65  even if the file
37980 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20  name used.** to 
37990 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
379a0 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73  e originally was
379b0 20 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69   a URI or relati
379c0 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a  ve pathname..*/.
379d0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
379e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
379f0 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74  b_filename(sqlit
37a00 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68  e3 *db, const ch
37a10 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f  ar *zDbName);../
37a20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
37a30 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61  etermine if a da
37a40 74 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f  tabase is read-o
37a50 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nly.**.** ^The s
37a60 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e  qlite3_db_readon
37a70 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63  ly(D,N) interfac
37a80 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74  e returns 1 if t
37a90 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a  he database N.**
37aa0 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   of connection D
37ab0 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30   is read-only, 0
37ac0 20 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77   if it is read/w
37ad0 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e  rite, or -1 if N
37ae0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e   is not.** the n
37af0 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73  ame of a databas
37b00 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e on connection 
37b10 44 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  D..*/.SQLITE_API
37b20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
37b30 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
37b40 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72   *db, const char
37b50 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a   *zDbName);../*.
37b60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
37b70 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61  d the next prepa
37b80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
37b90 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
37ba0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
37bb0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78  inter to the nex
37bc0 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
37bd0 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20  ement] after.** 
37be0 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64  pStmt associated
37bf0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
37c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37c10 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20  pDb.  ^If pStmt 
37c20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20  is NULL.** then 
37c30 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  this interface r
37c40 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
37c50 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72   to the first pr
37c60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37c70 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
37c80 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
37c90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e   connection pDb.
37ca0 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65    ^If no prepare
37cb0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73  d statement.** s
37cc0 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e  atisfies the con
37cd0 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20  ditions of this 
37ce0 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75  routine, it retu
37cf0 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  rns NULL..**.** 
37d00 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
37d10 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65  nnection] pointe
37d20 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r D in a call to
37d30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  .** [sqlite3_nex
37d40 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73  t_stmt(D,S)] mus
37d50 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70  t refer to an op
37d60 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  en database.** c
37d70 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e  onnection and in
37d80 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74   particular must
37d90 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70   not be a NULL p
37da0 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  ointer..*/.SQLIT
37db0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 73 74  E_API sqlite3_st
37dc0 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74  mt *sqlite3_next
37dd0 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70  _stmt(sqlite3 *p
37de0 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  Db, sqlite3_stmt
37df0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
37e00 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
37e10 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
37e20 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
37e30 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
37e40 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
37e50 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
37e60 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
37e70 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
37e80 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
37e90 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
37ea0 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49  action is [COMMI
37eb0 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a  T | committed]..
37ec0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
37ed0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
37ee0 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
37ef0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
37f00 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
37f10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37f20 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
37f30 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  en..** ^The sqli
37f40 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
37f50 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
37f60 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
37f70 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
37f80 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
37f90 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
37fa0 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b  ion is [ROLLBACK
37fb0 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e   | rolled back].
37fc0 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
37fd0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
37fe0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
37ff0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
38000 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
38010 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
38020 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
38030 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70  idden..** ^The p
38040 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
38050 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74  passed through t
38060 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  o the callback..
38070 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
38080 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
38090 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  hook function re
380a0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a  turns non-zero,.
380b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ** then the comm
380c0 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
380d0 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
380e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
380f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
38100 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74  D,C,P) and sqlit
38110 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
38120 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
38130 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20  s.** return the 
38140 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
38150 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
38160 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  l of the same fu
38170 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65  nction.** on the
38180 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
38190 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
381a0 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
381b0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72  e first call for
381c0 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f   each function o
381d0 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n D..**.** The c
381e0 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61  ommit and rollba
381f0 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  ck hook callback
38200 73 20 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72  s are not reentr
38210 61 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ant..** The call
38220 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  back implementat
38230 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
38240 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
38250 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
38260 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
38270 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
38280 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  d the callback. 
38290 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
382a0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
382b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
382c0 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
382d0 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
382e0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
382f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
38300 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
38310 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
38320 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f   commit.** or ro
38330 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74  llback hook in t
38340 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
38350 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e  ** Note that run
38360 6e 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  ning any other S
38370 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69  QL statements, i
38380 6e 63 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20  ncluding SELECT 
38390 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f  statements,.** o
383a0 72 20 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67  r merely calling
383b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
383c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
383d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
383e0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
383f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38400 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
38410 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
38420 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
38430 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73  ph..**.** ^Regis
38440 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
38450 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
38460 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
38470 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f  .** ^When the co
38480 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  mmit hook callba
38490 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ck routine retur
384a0 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f  ns zero, the [CO
384b0 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69  MMIT].** operati
384c0 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  on is allowed to
384d0 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c   continue normal
384e0 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d  ly.  ^If the com
384f0 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75  mit hook.** retu
38500 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
38510 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20  en the [COMMIT] 
38520 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
38530 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a  o a [ROLLBACK]..
38540 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b  ** ^The rollback
38550 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64   hook is invoked
38560 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74   on a rollback t
38570 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  hat results from
38580 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f   a commit.** hoo
38590 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d  k returning non-
385a0 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74  zero, just as it
385b0 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61   would be with a
385c0 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63  ny other rollbac
385d0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  k..**.** ^For th
385e0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
385f0 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
38600 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
38610 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f   have been.** ro
38620 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
38630 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
38640 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
38650 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
38660 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
38670 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
38680 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
38690 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a  ack to occur..**
386a0 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63   ^The rollback c
386b0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
386c0 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
386d0 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
386e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
386f0 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
38700 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
38710 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
38720 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
38730 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  o the [sqlite3_u
38740 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e  pdate_hook()] in
38750 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49  terface..*/.SQLI
38760 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
38770 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
38780 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
38790 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
387a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
387b0